wrg-devguard 0.2.3

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.

wrg-devguard

Developer-first AI safety checks: prompt-policy lint, secret scanning, and log scanning with PII detection.

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

pip install wrg-devguard

For YAML policy support:

pip install "wrg-devguard[yaml]"

Quick start

# 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

# .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 for all inputs.

GitHub Actions Marketplace

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

- 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:

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:

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:

- 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 for the latest published versions.

Claude Code skill

Drop the skill into your workspace:

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:

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.

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:

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

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

License

MIT. See LICENSE.

Contributing

Issues and PRs welcome. For substantial changes, open an issue first to discuss scope. See CONTRIBUTING.md for dev setup + PR bar; CODE_OF_CONDUCT.md; SECURITY.md.

Sister WRG-11 packages

Part of the WRG-11 PyPI portfolio:

• instinct-mcp -- MCP server for capturing recurring patterns into structured memory
• wrg-mcp-server -- MCP bridge for the WinstonRedGuard monorepo
• wrg-rule-lab -- Local-first deterministic rule evaluation engine (zero-dep, stdlib-only)
• ai-security-toolkit -- Offensive + defensive AI/LLM security tools, labs, CTF writeups, research

Built by WRG-11.

---

wrg-devguard was previously developed inside the private WinstonRedGuard monorepo at apps/wrg_devguard/. This standalone repo (WRG-11/wrg-devguard) is now the canonical source post the WRG-11 brand consolidation; the monorepo copy is no longer the source of truth.