Metadata-Version: 2.4
Name: wrg-devguard
Version: 0.2.5
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: WRG-11
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: pytest-cov>=4; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Dynamic: license-file

# wrg-devguard

> 💡 **Found this useful?** ⭐ Star the repo (helps others find it) and subscribe to weekly detection-engineering writeups at [Detection Frontier](https://detection-frontier.kit.com/subscribe).

[![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)
[![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)](#)

> **Developer-first AI safety scanner — catches leaked secrets, AI prompt-policy violations, and PII in logs before they ship. Zero runtime deps. Ships as CLI + GitHub Action + Claude skill + Cursor rule.**

`wrg-devguard` is a zero-dependency Python scanner that catches three 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
3. **PII in log files** — 13 patterns across 9 categories with redaction-by-design (raw secrets never leave the process)

## Why another secret scanner?

- **Zero runtime deps** — core scanner is stdlib only, so `pip install` is instant and works in any sandbox (CI minutes + supply chain hygiene)
- **Policy lint in the same tool** — most scanners only do secrets. wrg-devguard also catches AI prompt-policy violations (deny-listed patterns, hardcoded system prompts, PII in AI-facing text)
- **AI-native UX** — ships with a Claude Code 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 (`schemas/log_scan_result.schema.json`) that never breaks

## Use cases

- **Pre-commit secret block** — Claude Code skill auto-triggers on "is this safe to commit" / "scan for leaks"
- **GitHub PR check** — composite action blocks PR merges that introduce error-severity findings
- **AI prompt audit** — scan a repo of prompt templates for policy violations (e.g., hardcoded system overrides)
- **Log file PII sweep** — `scan-logs` redacts secrets + 13 PII patterns from log fixtures before sharing
- **Scheduled audit + SARIF upload** — weekly cron emits SARIF, uploads to GitHub code-scanning UI

## Quick start

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

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

# PII + secret scan on log files
wrg-devguard scan-logs --path my.log --json-out logs.json

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

## How it compares

| Project | Secret scan | Prompt-policy lint | PII in logs | Zero deps | AI editor integration | Best for |
|---|---|---|---|---|---|---|
| **wrg-devguard** | ✅ | ✅ | ✅ (13 patterns / 9 cats) | ✅ stdlib only | ✅ Claude skill + Cursor rule | AI-coding workflows + CI |
| [gitleaks](https://github.com/gitleaks/gitleaks) | ✅ (deep) | ❌ | ❌ | ⚠️ Go binary | ❌ | High-fidelity secret-only scanning |
| [trufflehog](https://github.com/trufflesecurity/trufflehog) | ✅ (700+ detectors) | ❌ | ❌ | ⚠️ Go binary | ❌ | Deep secret detection + verification |
| [detect-secrets](https://github.com/Yelp/detect-secrets) | ✅ | ❌ | ❌ | ⚠️ Python + plugins | ⚠️ Pre-commit only | Yelp-style pre-commit baseline |
| [bandit](https://github.com/PyCQA/bandit) | ❌ | ❌ | ❌ | ✅ Python | ❌ | Python AST security issues (CWE-style) |

(wrg-devguard ships an optional `bandit` wrapper subcommand for one-stop scanning.)

## When to reach for wrg-devguard

- Your team uses AI coding assistants (Claude Code, Cursor) and wants the scanner integrated, not bolted on
- You need both **secret scanning** AND **AI prompt-policy lint** in one tool, not two
- Zero-dep is non-negotiable (locked-down CI sandbox, supply chain concerns)
- You want a stable JSON schema you can build dashboards/automation against

## Where wrg-devguard loses today (honest delta)

- **Detection depth vs trufflehog** — trufflehog has 700+ detectors with verification (live API checks); wrg-devguard's secret pattern library is curated but smaller
- **Older / more battle-tested alternatives** — gitleaks, detect-secrets, trufflehog each have 5+ years of community PRs catching edge cases
- **No JavaScript / Go / Rust ecosystem-specific detectors** — wrg-devguard is Python-first; other-language secret formats are covered but not exhaustively
- **GUI / dashboard YOK** — JSON output is solid but rendering it is on you (or use the sister `wrg-portfolio` dashboard for cross-repo aggregation)

If deep verified secret detection is your primary need, pair wrg-devguard (for prompt-policy + PII + CI hygiene) with trufflehog (for high-fidelity secret verification).

## Ships as

- **Python package**: `pip install wrg-devguard` (CLI + library)
- **GitHub Action**: drop-in composite action for any repo (`uses: WRG-11/wrg-devguard@v0`)
- **Claude Code skill**: `.claude/skills/wrg-devguard/SKILL.md`
- **Cursor rule**: `.cursor/rules/wrg-devguard.mdc`

## 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. 3-line minimum drop-in:

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

### Action 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`) |

### Action outputs

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

### Action use cases

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

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

**Scheduled audit — emit SARIF, never fail, upload to code-scanning:**

```yaml
- uses: WRG-11/wrg-devguard@v0
  id: dg
  with:
    format: sarif
    fail-on: none
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.dg.outputs.report-path }}
```

**Monorepo path filter:**

```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
- `@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 surfaces the skill automatically on prompts like "scan for secrets", "is this safe to commit", or "check for leaks".

## Cursor rule

```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 applies 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).

## All 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 combined
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 logs (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 emits a frozen JSON contract documented at [`schemas/log_scan_result.schema.json`](schemas/log_scan_result.schema.json). Highlights:

- `schema_version: "1"` (frozen for the v0.2.0 line)
- `findings[].pattern_id` — stable `<NAMESPACE>-<NNN>` identifiers (e.g., `AWS-001`, `EMAIL-001`); superseded patterns get a new ID, never reuse
- `findings[].redacted_excerpt` — middle-masked; raw secrets never appear in output
- Open-enum-friendly categories + severities (consumers should accept unknown values gracefully)

Validation tests: `tests/schemas/test_log_scan_result_schema.py` (28 cases). Run locally with `pytest tests/schemas/ -v`.

## Install (full options)

```bash
pip install wrg-devguard                  # core (stdlib only)
pip install "wrg-devguard[yaml]"          # YAML policy support
```

## Development

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

## Sister WRG-11 packages

Part of the WRG-11 PyPI portfolio:

- [`instinct-mcp`](https://pypi.org/project/instinct-mcp/) — Self-learning memory for AI coding agents (MCP server)
- [`wrg-mcp-server`](https://pypi.org/project/wrg-mcp-server/) — MCP bridge for the WinstonRedGuard monorepo (60+ security/threat-intel tools)
- [`wrg-rule-lab`](https://pypi.org/project/wrg-rule-lab/) — Local-first deterministic rule evaluation engine (zero-dep, stdlib-only)
- [`ai-security-toolkit`](https://github.com/WRG-11/ai-security-toolkit) — Offensive + defensive AI/LLM security tools, labs, CTF writeups, research

Built by [WRG-11](https://github.com/WRG-11).

## Contributing

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

## License

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

## Migration note

`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.
