Wardline
Semantic-tainting static analysis for Python. Wardline tracks untrusted data across your codebase and flags trust-boundary violations — statically, with zero runtime dependencies.
Three trust decorators
Declare trust at the source with @external_boundary,
@trust_boundary, and @trusted. Undecorated
code stays in the developer-freedom zone — opt-in, fail-closed.
Eleven policy rules
PY-WL-101 through PY-WL-111 catch trust-boundary
leaks, untrusted data reaching deserialization, exec, and shell sinks, and
validators that can’t say “no.”
SARIF and JSONL output
Emit findings as SARIF for code-scanning dashboards or JSONL for tooling.
Gate CI with wardline scan --fail-on ERROR.
Agent-ready: MCP & LLM triage
A built-in MCP server lets coding agents scan and explain taint. An opt-in LLM triage judge, baselines, and waivers keep the signal clean.
Install¶
pip install "wardline[scanner]"
Wardline ships in layers, so you only pull what you use:
| Install | Pulls in | Gives you |
|---|---|---|
wardline (base) |
nothing | the analysis engine as a zero-dependency library |
wardline[scanner] |
pyyaml, jsonschema, click | the wardline scan command-line tool |
The wardline scan CLI lives in the scanner extra, so install
wardline[scanner] to run the examples below. Everything in the
Loom integration guide — SARIF output, the Filigree emitter,
Clarion conformance — also ships in scanner (the Filigree emitter uses only
the standard library), so no further extra is required.
30-second example¶
Point wardline scan at a directory:
wardline scan . --format jsonl
scanned 2 file(s); 4 finding(s) — 0 suppressed (0 baseline / 0 waiver / 0 judged), 1 new -> findings.jsonl
In JSONL mode the findings are written to findings.jsonl in the current
directory; the line above is the run summary. One of those findings flags a
trust-boundary violation:
{"rule_id": "PY-WL-101", "severity": "ERROR", "kind": "defect", "qualname": "service.current_user", "location": {"path": "service.py", "line_start": 7, "line_end": 8, "col_start": 0, "col_end": 26}, "message": "service.current_user declares return trust INTEGRAL but actually returns EXTERNAL_RAW (less trusted) — untrusted data reaches a trusted producer", "properties": {"declared_return": "INTEGRAL", "actual_return": "EXTERNAL_RAW"}, "suppressed": "active"}
That is Wardline reporting that a function annotated as a trusted producer actually returns raw, untrusted data — a trust-boundary leak. The Getting Started guide walks through this finding field by field.
Next steps¶
- Getting Started — install, run a first scan, and read a finding.
- The model — trust tiers, boundaries, and how taint flows.
- Arming agents — using Wardline to give coding agents a trust-boundary check.
The Loom suite
Wardline is one of four Loom citizens — agent-first tooling built on “humans on the loop, not in the loop.” Each is zero-config and opt-in: enterprise-class for one-to-two-developer teams, without enterprise weight.