llmpromptdefender 0.4.0

Static security scanner for LLM and agentic source code — finds prompt-injection, context-leak, PII, RAG, and agent-tool vulnerabilities before deployment.

llmpromptdefender

Static security scanner for LLM and agentic source code.

Reads your code the way a compiler does. Never runs the code, never calls a model API, never sends data anywhere. Produces a list of findings keyed to file and line, plus remediation guidance — before you ship.

Install

pip install llmpromptdefender

Optional extras:

pip install "llmpromptdefender[pdf]"   # PDF reports
pip install "llmpromptdefender[tui]"   # full-screen Textual TUI
pip install "llmpromptdefender[all]"   # both extras

60-second demo

# scan the current project
llmpromptdefender scan .

# scan with syntax-highlighted detail cards on the top findings
llmpromptdefender scan . --detail --detail-limit 5

# only fail CI on critical findings
llmpromptdefender scan . --fail-on critical

# write SARIF for GitHub Code Scanning
llmpromptdefender scan . --output results.sarif

# launch the web dashboard against an existing results.json
llmpromptdefender dashboard --input results.sarif

# explain any rule
llmpromptdefender explain PL-001

No arguments? llmpromptdefender drops you into an interactive shell with tab-completed commands, paths, severities, layers, and rule codes — up/down arrows recall history; Ctrl-C clears the line; exit or Ctrl-D quits.

llmpromptdefender ~/projects › scan tests/fixtures/vulnerable --se<TAB>verity critical
llmpromptdefender ~/projects › explain PL<TAB>
  PL-001  PL-002  PL-003  PL-004  PL-005  PL-006  PL-007  PL-008

What it scans — seven threat layers

Layer	Code prefix	Focus
1. Prompt injection entry points	PL	f-strings, concatenation, .format(), kwarg payloads (question, query, messages) flowing into prompts
2. Data exfiltration via context	CL	object __dict__ dumps, DB query results, env vars, app config, secret-named identifiers in prompts
3. PII pattern detection	PI	SSN, credit card (Luhn-validated), email, phone, passport, IP, PII-named attributes
4. System prompt leakage	SP	system prompts returned to callers or exposed in response payloads
5. RAG pipeline contamination	RP	unbounded similarity_top_k / top_k, user-controlled fetch URLs, recursive retrieval loops
6. Agent and tool-call security	AG	subprocess.* (shell=True), eval/exec with dynamic input, unbounded tool sets, self-feedback loops, unsanitised memory writes
7. Multi-agent trust boundaries	MA	blind cross-agent execution, full capability inheritance, shared memory across trust tiers, open allow_delegation

CLI surface (selected)

# scanning
llmpromptdefender scan PATH                  # the main command
llmpromptdefender scan . --layers injection,leak,pii
llmpromptdefender scan . --severity critical,high
llmpromptdefender scan . --confidence high   # show only high-confidence findings
llmpromptdefender scan . --jobs 4            # parallel scan
llmpromptdefender scan . --incremental       # use the file-hash cache
llmpromptdefender scan . --diff git:origin/main   # only files changed vs base
llmpromptdefender scan . --baseline baseline.json # only fail on new findings
llmpromptdefender scan . --rules-dir ./custom-rules

# reports (input is a results.json)
llmpromptdefender report html    results.json --output report.html
llmpromptdefender report pdf     results.json --output report.pdf
llmpromptdefender report dashboard results.json --output dashboard.html
llmpromptdefender report sarif   results.json --output report.sarif
llmpromptdefender report markdown results.json --output report.md
llmpromptdefender report csv     results.json --output results.csv
llmpromptdefender report trend                       # findings across history

# rules
llmpromptdefender rules list
llmpromptdefender rules layers
llmpromptdefender rules packs
llmpromptdefender rules show PL-001
llmpromptdefender rules disable PL-005 --config .llmpromptdefender.toml
llmpromptdefender rules install ./my-pack.yaml
llmpromptdefender rules uninstall my-pack

# pre-commit hook
llmpromptdefender hooks install
llmpromptdefender hooks status
llmpromptdefender hooks remove

# misc
llmpromptdefender baseline create        # write a baseline.json from a clean scan
llmpromptdefender diff before.json after.json
llmpromptdefender config show
llmpromptdefender cache info
llmpromptdefender history show
llmpromptdefender dashboard              # web UI
llmpromptdefender tui                    # full-screen Textual UI (needs [tui])
llmpromptdefender watch .                # rescan on file save
llmpromptdefender init                   # write a default config file

Exit codes:

• 0 no findings (or only info / below --fail-on)
• 1 findings at or above --fail-on (default high)
• 2 invalid arguments, unknown rule code, unreadable target

Configuration

llmpromptdefender looks for .llmpromptdefender.toml, .llmpromptdefender.yaml, or a [tool.llmpromptdefender] table in pyproject.toml. Run llmpromptdefender init to scaffold the defaults.

# .llmpromptdefender.toml
target = "."
layers = []            # empty = all seven
fail_on = "high"
exclude = [".venv", "node_modules", "build", "dist"]
rule_packs = []        # empty = all builtin packs
ignore = []            # rule codes to suppress, e.g. ["PL-005"]
dashboard_host = "127.0.0.1"
dashboard_port = 8765

How it works

• Python sources parsed with the stdlib ast module.
• JavaScript / TypeScript scanned with carefully scoped regex heuristics (default) or the opt-in esprima path with the js extra.
• YAML / JSON configs (agent definitions, tool manifests) walked structurally.
• Rules declared in YAML packs under llmpromptdefender/rules/. User-installed packs live under ~/.llmpromptdefender/rules/ and can be managed via the rules install / uninstall / packs commands.
• Identifier matching is token-boundary aware: internal_request_url is split into {internal, request, url} so a hardcoded URL doesn't trip the request substring.
• Files we can't read produce ERR-001 / ERR-002 / ERR-003 findings — we never silently skip a file and grade the project "A+".

Development

git clone <your fork>
cd llmpromptdefender
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,pdf,tui]"
pytest                           # 100+ unit tests
python tools/check_every_command.py   # 63-command end-to-end harness

License

MIT — see LICENSE.