appsec

The App Security toolbelt — a stateful CLI that guides an AI agent or a human through a rigorous, resumable vulnerability hunt. It scopes the target by project type, language, and surface; hands back a prioritized checklist of what to look for and where; and records every finding and decision to a local append-only JSONL log so the hunt can pause, resume, and be audited.

appsec is a guide and state-keeper, not a scanner or exploit engine — it does not run payloads or replace semgrep/trivy/CodeQL. Its output is guidance, checklist state, and recorded findings.

Install

uv sync

The hunt loop

uv run appsec learn                      # get into the app-sec frame of mind
uv run appsec learn --scaffold web_api   # emit a portable template + a SKILL.md kit

# Scope the target — derives a prioritized checklist keyed to the KB:
uv run appsec scope \
  --project-type backend --language python \
  --surface internet-facing --use-case "payments API" --targeted-system acme-api

uv run appsec status                     # read-only: coverage + recommended next item
uv run appsec finding add \
  --location app/db.py:42 --class "A03:2021-Injection / CWE-89" \
  --severity High --evidence "string-formatted SQL" --item web-sql-injection

uv run appsec report --out appsec-report.md   # export findings + coverage
uv run appsec resume                     # come back tomorrow: exact open/checked/finding state

Every verb takes --json for agent-mode (deterministic, machine-parseable on stdout; diagnostics on stderr). State lives under .appsec/hunt.jsonl in the current repo.

Knowledge base

v1 covers two target domains, grounded in the OWASP Top 10 (2021) with canonical CWE ids and a Low/Medium/High/Critical severity scale:

• web app + API/backend — the OWASP Top 10 classes.
• CLI / library — path traversal, command injection, unsafe deserialization, supply-chain/dependency exposure, privilege boundaries.

The mapping from scope dimensions to vulnerability classes lives in declarative YAML under appsec/knowledge/, so coverage grows by editing data, not code. Cloud/IaC/container (#18) and LLM-app/agent-surface (#19) coverage are tracked follow-ups.

Test / lint

uv run pytest -n auto
uv run flake8 --config=.flake8 appsec/ tests/
uv run black appsec/ tests/ && uv run isort appsec/ tests/

Docs

The design trail lives in docs/specs/ (the converged spec) and docs/plans/ (the buildable plan), both produced with the /think → /spec-to-plan skills.