Metadata-Version: 2.4
Name: wrg-devguard
Version: 0.2.2
Summary: Developer-first AI safety checks: prompt-policy lint, secret scanning, and log scanning with PII detection. Zero-dep CLI + GitHub Action + Claude Skill + Cursor Rule.
Author: Yakuphan Yucel
License-Expression: MIT
Project-URL: Homepage, https://github.com/WRG-11/wrg-devguard
Project-URL: Repository, https://github.com/WRG-11/wrg-devguard
Project-URL: Issues, https://github.com/WRG-11/wrg-devguard/issues
Project-URL: Changelog, https://github.com/WRG-11/wrg-devguard/releases
Keywords: security,secret-scanning,policy-lint,ai-safety,prompt-security,devsecops,pre-commit,github-action,claude-skill,cursor-rule
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Dynamic: license-file

# wrg-devguard

[![PyPI version](https://img.shields.io/pypi/v/wrg-devguard?color=%2334D058&label=pypi)](https://pypi.org/project/wrg-devguard/)
[![Python](https://img.shields.io/pypi/pyversions/wrg-devguard)](https://pypi.org/project/wrg-devguard/)
[![Downloads](https://img.shields.io/pypi/dm/wrg-devguard?label=downloads%2Fmo)](https://pypistats.org/packages/wrg-devguard)
[![CI](https://github.com/WRG-11/wrg-devguard/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/WRG-11/wrg-devguard/actions/workflows/ci.yml)
[![CodeQL](https://github.com/WRG-11/wrg-devguard/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/WRG-11/wrg-devguard/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Developer-first AI safety checks: prompt-policy lint + secret scanning.**

Zero-dependency Python CLI that scans a repository for two classes of issues
before your PR lands:

1. **Leaked secrets** — API keys, private keys, tokens, common credential
   formats in tracked files.
2. **Prompt-policy violations** — deny-listed patterns in prompts, system
   messages, and AI-facing text assets (configurable via JSON policy).

Ships as:

- A Python package (`pip install wrg-devguard`)
- A GitHub Action (drop-in composite action for any repo)
- A Claude Code skill (`.claude/skills/wrg-devguard/`)
- A Cursor rule (`.cursor/rules/wrg-devguard.mdc`)

No external dependencies in the core scanner (stdlib only). Optional `[yaml]`
extra for YAML policy files. Optional `bandit` subcommand for Python security
scanning.

## Install

```bash
pip install wrg-devguard
```

For YAML policy support:

```bash
pip install "wrg-devguard[yaml]"
```

## Quick start

```bash
# Run both checks and fail on any high-severity finding
wrg-devguard check --path . --fail-on error

# Scan only for leaked secrets
wrg-devguard scan-secrets --path .

# Lint AI-facing text assets against a policy
wrg-devguard lint-policy --path . --profile strict

# Emit a JSON report for CI
wrg-devguard check --path . --json-out wrg-devguard-report.json
```

## GitHub Action

```yaml
# .github/workflows/security.yml
name: security
on: [pull_request, push]

jobs:
  wrg-devguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: WRG-11/wrg-devguard@v0
        with:
          profile: strict
          fail-on: error
```

See [`action.yml`](./action.yml) for all inputs.

## GitHub Actions Marketplace

3-line quickstart (drop into any `.github/workflows/*.yml`):

```yaml
- uses: WRG-11/wrg-devguard@v0
  with:
    path: .
    fail-on: error
```

### Inputs

| Name | Required | Default | Description |
|---|---|---|---|
| `path` | no | `.` | Root path to scan |
| `fail-on` | no | `error` | Fail threshold: `error`, `warn`, `none` |
| `format` | no | `text` | Report format: `text`, `json`, `sarif` |
| `profile` | no | `baseline` | Policy profile: `baseline` or `strict` |
| `allowlist` | no | _empty_ | Optional path to allowlist JSON |
| `python-version` | no | `3.12` | Python version installed by the action |
| `version` | no | _latest_ | Pip version spec (e.g. `==0.1.1`) |

### Outputs

| Name | Description |
|---|---|
| `findings-count` | Total number of findings produced by the scan |
| `report-path` | Path to the generated report (empty when `format: text`) |

### Use cases

**1. PR check — block any error-severity finding:**

```yaml
name: security
on: pull_request
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: WRG-11/wrg-devguard@v0
        with:
          path: .
          fail-on: error
```

**2. Scheduled audit — emit SARIF, never fail the job, upload to code-scanning:**

```yaml
name: weekly-audit
on:
  schedule:
    - cron: '0 6 * * 1'
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - id: dg
        uses: WRG-11/wrg-devguard@v0
        with:
          format: sarif
          fail-on: none
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.dg.outputs.report-path }}
```

**3. Monorepo path filter — scan only one app, warn-level threshold:**

```yaml
- uses: WRG-11/wrg-devguard@v0
  with:
    path: apps/payments
    profile: strict
    fail-on: warn
    format: json
```

### Pinning

- `@v0` — moving major tag during the beta v0.x line, fast-forwards on every minor/patch release. Will flip to `@v1` on the v1.0.0 ship.
- `@v0.2.2` — immutable release tag (recommended for reproducible CI)

See the [Marketplace listing](https://github.com/marketplace/actions/wrg-devguard) for the latest published versions.

## Claude Code skill

Drop the skill into your workspace:

```bash
mkdir -p .claude/skills/wrg-devguard
curl -L https://raw.githubusercontent.com/WRG-11/wrg-devguard/main/.claude/skills/wrg-devguard/SKILL.md \
  -o .claude/skills/wrg-devguard/SKILL.md
```

Claude Code will surface the skill automatically when you ask things like
"scan for secrets", "is this safe to commit", or "check for leaks".

## Cursor rule

Drop the rule into your workspace:

```bash
mkdir -p .cursor/rules
curl -L https://raw.githubusercontent.com/WRG-11/wrg-devguard/main/.cursor/rules/wrg-devguard.mdc \
  -o .cursor/rules/wrg-devguard.mdc
```

Cursor will apply the rule before suggesting any `git commit` command.

## Policy file

Default lookup order:

1. `--policy <path>` argument if provided
2. `.wrg/policy.json` at the repo root
3. Built-in defaults

Profiles:

- `baseline` → PR-friendly baseline (recommended for CI, default)
- `strict` → stricter local/release audits (use `--profile strict`)

Place custom policies in `.wrg/policy.json` (JSON) or `.wrg/policy.yaml`
(requires `[yaml]` extra).

## Commands

```
wrg-devguard profiles                           # list available profiles
wrg-devguard lint-policy --path .               # policy lint only
wrg-devguard scan-secrets --path .              # secret scan only
wrg-devguard check --path .                     # lint-policy + scan-secrets, single JSON report
wrg-devguard check --path . --profile strict
wrg-devguard check --path . --json-out report.json
wrg-devguard check --path . --fail-on warning
wrg-devguard check --path . --allowlist .wrg/allowlist.json
wrg-devguard scan-logs --path <log-file>        # PII + secret scan on log files (v0.2.0)
wrg-devguard scan-logs --path . --json-out logs.json
wrg-devguard bandit --path src/                 # optional: bandit wrapper
```

## Exit codes

- `0` — no findings above threshold
- `1` — findings at or above `--fail-on` threshold
- `2` — configuration or input error

## Output schema

The `scan-logs` subcommand (shipped in v0.2.0) emits a frozen JSON contract
documented at [`schemas/log_scan_result.schema.json`](schemas/log_scan_result.schema.json).

Consumers (the GitHub Action, the Control Center log viewer, future CI
integrations) parse against this schema. Highlights:

- `schema_version`: `"1"` (frozen for the v0.2.0 line).
- `source`: one of `manual`, `ci`, `cc-endpoint`. v0.2.0 ships `manual` only.
- `findings[].pattern_id`: stable `<NAMESPACE>-<NNN>` identifiers (`AWS-001`,
  `EMAIL-001`, etc.). Patterns are versioned by ID — superseded patterns get
  a new ID, never reuse.
- `findings[].redacted_excerpt`: producers MUST middle-mask the matched value.
  Raw secrets never appear in the output.
- Categories and severities are open-enum-friendly: consumers should accept
  unknown values gracefully (treat as a generic finding) so v0.3.0 additions
  don't break v0.2.0 readers.

Validation tests live at `tests/schemas/test_log_scan_result_schema.py`
(28 cases covering self-validation, fixture acceptance, and malformed-payload
rejection). To run them locally:

```bash
pip install -e ".[dev]"
pytest tests/schemas/ -v
```

## Why another secret scanner?

- **Zero runtime deps** — the core scanner is stdlib only, so `pip install` is
  instant and works in any sandbox.
- **Policy lint in the same tool** — most scanners only do secrets. We also
  catch prompt-policy violations (deny-listed patterns, hardcoded system
  prompts, PII in AI-facing text).
- **AI-native UX** — ships with a Claude skill and a Cursor rule so the
  scanner runs automatically inside your AI coding assistant, not just in CI.
- **Stable JSON schema** — `check --json-out` emits a versioned schema that
  never breaks.

## Development

```bash
git clone https://github.com/WRG-11/wrg-devguard.git
cd wrg-devguard
pip install -e ".[dev]"
pytest -q
```

## License

MIT. See [LICENSE](./LICENSE).

## Contributing

Issues and PRs welcome. For substantial changes, open an issue first to
discuss scope.

---

Part of the [WinstonRedGuard](https://github.com/WRG-11/WinstonRedGuard)
ecosystem (private monorepo). `apps/wrg_devguard/` there is the canonical
source; this repo is the public distribution mirror kept in sync on every
release.
