Metadata-Version: 2.4
Name: appsec
Version: 0.4.0
Summary: appsec — an application-security agent (greenfield AgentCulture sibling).
Project-URL: Homepage, https://github.com/agentculture/appsec
Project-URL: Issues, https://github.com/agentculture/appsec/issues
Author: AgentCulture
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 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

```bash
uv sync
```

## The hunt loop

```bash
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](https://github.com/agentculture/appsec/issues/18)) and
LLM-app/agent-surface ([#19](https://github.com/agentculture/appsec/issues/19))
coverage are tracked follow-ups.

## Test / lint

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