attackmap 0.4.6__tar.gz → 0.4.15__tar.gz

{attackmap-0.4.6/src/attackmap.egg-info → attackmap-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.4.6
+Version: 0.4.15
 Summary: AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints.
 Author: AttackMap Contributors
 Author-email: Matthew Davis <matthewd@matthewd.xyz>
@@ -34,6 +34,7 @@ License-File: LICENSE
 Requires-Dist: typer>=0.12.3
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: networkx>=3.3
+Requires-Dist: PyYAML>=6.0
 Provides-Extra: llm
 Requires-Dist: anthropic>=0.40.0; extra == "llm"
 Requires-Dist: openai>=1.60.0; extra == "llm"
@@ -76,12 +77,24 @@ managers who need to triage an unfamiliar codebase.
 [![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
 [![PyPI](https://img.shields.io/pypi/v/attackmap.svg)](https://pypi.org/project/attackmap/)
 
-> **Status: beta (v0.4.0).** Core engine and 14 analyzer plugins are published
+> **Status: beta (v0.4.15).** Core engine and 14 analyzer plugins are published
 > to PyPI, Homebrew, and GHCR and validated against real-world codebases.
 > AttackMap is heuristic by design — findings are confidence-tiered evidence,
 > not proof. See [Project status](#project-status) for what's solid and what's
 > still maturing.
 
+### The macOS app
+
+Prefer a GUI? AttackMap ships a native macOS front-end that drives this CLI and
+renders every result view — install with `brew install --cask mlaify/tap/attackmap-app`
+(the cask depends on the `attackmap` formula, so this pulls the CLI too).
+
+| Overview | Exploitability |
+|---|---|
+| [![AttackMap macOS app — overview](https://raw.githubusercontent.com/mlaify/AttackMap/main/docs/screenshots/04-overview.png)](https://docs.matthewd.xyz/gui/) | [![AttackMap macOS app — exploitability](https://raw.githubusercontent.com/mlaify/AttackMap/main/docs/screenshots/06-exploitability-ranked.png)](https://docs.matthewd.xyz/gui/) |
+
+*Scanning OWASP Juice Shop. Full walkthrough in the [macOS app docs](https://docs.matthewd.xyz/gui/); source at [mlaify/AttackMap-mac](https://github.com/mlaify/AttackMap-mac).*
+
 ---
 
 ## Quickstart
@@ -186,6 +199,7 @@ Every `attackmap analyze` run writes:
 | `defensive-review-llm.md` *(with `--llm`)* | Claude-narrated review |
 | `defensive-review-llm.meta.json` *(with `--llm`)* | Backend, model, token usage |
 | `vulnerability-hypotheses.md` *(with `--hunt`)* | LLM-generated, evidence-cited exploit-chain **hypotheses** to confirm (leads, not detections) |
+| `triage.md` *(with `--triage`)* | Clustered, de-duplicated, ranked shortlist of the existing findings (LLM-backed; deterministic fallback) |
 
 ### GitHub Code Scanning integration
 
@@ -271,6 +285,48 @@ on unrelated commits, so a finding that persists across scans has the same id
 in both. The diff has three sections — **New**, **Persisted**, **Resolved** —
 which drop cleanly into a PR comment.
 
+### Suppressing findings
+
+Silence a residual false positive without going blind to new signal. Two
+mechanisms, both honored across every pass:
+
+**Repo-level baseline** — `.attackmap-suppress.yaml` at the repo root:
+
+```yaml
+version: 1
+suppress:
+  # by stable finding id (the 16-hex id in attackmap-report.json)
+  - id: 1a2b3c4d5e6f7a8b
+    reason: accepted risk, tracked in JIRA-1234
+
+  # by rule (a slug of the finding title — same string as the SARIF ruleId),
+  # optionally scoped to paths
+  - rule: hard-coded-secret-literals-were-found-in-source-or-config
+    reason: example keys in docs, never shipped
+    paths: ["docs/**", "examples/**"]
+
+  # by path only — any finding whose evidence is *entirely* within these globs
+  - path: "vendor/**"
+    reason: third-party code, out of scope
+```
+
+A `path` selector matches a finding only when **every** file its evidence cites
+falls under the glob, so a finding that also touches live code is never hidden.
+`*` spans path separators (`vendor/*` covers the whole subtree).
+
+**Inline directives** — a comment on the flagged line, in any language:
+
+```python
+API_KEY = "AKIA…"  # attackmap:ignore[hard-coded-secret-literals-were-found-in-source-or-config] staging only
+```
+
+Suppressed findings are **not dropped**: they're excluded from
+`--fail-on-new-high` and the console summary, but retained in
+`attackmap-report.json` under `suppressed_findings` (with reasons) and marked
+with a SARIF `suppressions` array so GitHub Code Scanning shows them as
+suppressed. Suppression counts print in the run summary. Use `--no-suppress`
+for a full unfiltered audit, or `--suppress-file PATH` to point elsewhere.
+
 ### Data-flow / injection detection
 
 A lightweight taint pass (Python + JS/TS) walks the import graph up to two hops
@@ -302,10 +358,27 @@ left on).
 
 Sinks that are only dangerous with attacker-controlled input (SSRF, SSTI, NoSQL,
 open redirect, `open`) are gated on a request-shaped identifier in the call — a constant URL or
-template is not flagged. It's a heuristic (import-edge ≠ call-edge), so findings
+template is not flagged. The walk is **call-graph-aware** (#138): for Python and
+JS/TS an import edge is kept only when the imported symbol is actually used in
+the file, so a dead import no longer fans a route out to that module's sinks
+(the plain import-graph remains the fallback for namespace/star/side-effect
+imports and for Go/PHP). It's still a heuristic (use ≉ proven call), so findings
 are evidence, not proof; confidence tapers with hop distance. Chains appear in
 `attackmap-report.json` under `scan.taint_chains`.
 
+**Sanitizer awareness.** When a sink-appropriate neutralizer is present in the
+sink file — `shlex.quote` / `escapeshellarg` (shell), `secure_filename` / path
+allow-listers (`open`), `is_safe_url` (redirect), `markupsafe.escape` (SSTI),
+driver escapers (SQL), mongo-sanitize (NoSQL) — the chain is marked
+`sanitized`, its confidence is downgraded well below the finding threshold, and
+the neutralizer is recorded in `sanitizer_evidence`. Sanitized chains stay in
+`scan.taint_chains` for audit but don't raise a HIGH finding or earn an
+exploitability score. Detection is file-granular (matching the import-walk's
+granularity), so it trades a little recall for precision. To extend the table,
+add a high-signal, sink-appropriate `(label, regex)` entry to
+`_SANITIZER_PATTERNS` in [`taint.py`](src/attackmap/taint.py) — keep it specific
+(a vague `validate(` would hide real bugs).
+
 Test and spec files (`tests/`, `__tests__/`, `*.test.*`, `test_*.py`, …) are
 excluded from all the heuristic passes above by default, since dangerous
 patterns in test scaffolding are rarely real exposure. Set
@@ -347,23 +420,87 @@ identifier; cipher/ECB tokens are matched case-sensitively so algorithm names
 aren't confused with prose (e.g. the French word "des"). Results appear under
 `scan.crypto_weaknesses`.
 
+### Hard-coded secret detection
+
+Two layers, precision-first. **Typed provider-signature detectors** recognize the
+distinctive shapes of leaked keys and fire at high confidence with a
+provider-specific `kind`:
+
+| Provider | Prefix / shape |
+|---|---|
+| AWS | `AKIA…` / `ASIA…` |
+| GitHub | `ghp_` / `gho_` / `ghu_` / `ghs_` / `ghr_` |
+| OpenAI | `sk-…` / `sk-proj-…` / `sk-svcacct-…` |
+| Anthropic | `sk-ant-…` |
+| GitLab / npm | `glpat-…` / `npm_…` |
+| Stripe / Slack / Google | `sk_live_…` / `xox[bpsare]-…` / `AIza…` |
+| SendGrid / Mailgun / Twilio | `SG.…` / `key-…` / `AC…` SID |
+| PEM / JWT | `-----BEGIN … PRIVATE KEY-----` / `eyJ….eyJ….…` (header verified) |
+
+Below the typed layer, a **Shannon-entropy fallback** catches high-entropy
+literals that don't match a known provider. It is calibrated to stay quiet:
+pure-hex hashes, URLs, version/number strings, base64/base32 alphabet constants
+(#96), Subresource-Integrity / lockfile digests (`sha384-…`), and UUIDs are
+suppressed, and a typed match always takes precedence over the entropy hit for
+the same span. Values are redacted (`ghp_…6789`) before they reach any report —
+the raw secret never appears. No liveness verification is performed. Results
+appear as `scan.secret_hints`.
+
+### GitHub Actions / CI workflow security
+
+CI config is a real attack surface. AttackMap parses `.github/workflows/*.yml`
+and flags supply-chain and code-execution risks, each a finding with an ATT&CK
+mapping:
+
+| Kind | Catches | Severity |
+|---|---|---|
+| `script_injection` | attacker-controlled context (`github.event.*.{title,body,message,…}`, `github.head_ref`) interpolated into a `run:` step | HIGH |
+| `pr_target_checkout` | `pull_request_target` + checkout of the PR head ref (untrusted code with secrets in scope) | HIGH |
+| `unpinned_action` | `uses: org/action@tag\|branch` instead of a pinned commit SHA | branch = MEDIUM, semver tag = LOW |
+| `secret_in_run` | `${{ secrets.* }}` expanded into a shell step (pass via `env:` instead) | MEDIUM |
+| `broad_permissions` | `permissions: write-all` at workflow or job level | MEDIUM |
+| `self_hosted_pr` | self-hosted runner on a `pull_request`/`pull_request_target` trigger | HIGH / MEDIUM |
+
+A hardened workflow — SHA-pinned actions, scoped `permissions:`, secrets via
+`env:`, no untrusted-context interpolation — produces nothing. Results appear
+under `scan.workflow_issues`.
+
+### Unauthenticated state-changing routes
+
+Raw `auth_hints` are signals, not conclusions — a monorepo emits hundreds. A
+fusion pass turns them into one precise finding: the public, state-changing
+(`POST/PUT/PATCH/DELETE`) routes with **no auth control on their own chain**. It
+resolves the control *per route* rather than by file proximity:
+
+- **Express/Koa/Fastify** — auth middleware in the route's arguments, or a global `app.use(...)` / `router.use(...)`.
+- **FastAPI/Flask** — an auth decorator, `dependencies=[Depends(...)]`, `Depends(<auth>)` / `Security(...)` in the signature, or a router-level dependency.
+- **Spring** — `@PreAuthorize` / `@Secured` / `@RolesAllowed` on the method or controller, or a global "authenticated" policy.
+
+Routes behind a control produce nothing, and the sensitive categories
+(webhook/admin/upload/auth) keep their own dedicated findings — so this only
+adds the general mutating-endpoint case, with the resolved chain as evidence.
+
 ### Broken object-level authorization (BOLA / IDOR)
 
 OWASP API Security #1. AttackMap flags a route as a BOLA/IDOR candidate when it
 composes three signals it already has:
 
-1. the route takes a **resource id** in the path (`/users/{id}`,
-   `/orders/:orderId`, `/docs/<int:doc_id>`), and
-2. it **reaches a datastore** — a DB hint in the same file/module, or a taint
-   chain from the route to a SQL execute sink, and
+1. the route takes a **resource id** — via a **path** template (`/users/{id}`,
+   `/orders/:orderId`), an id-bearing **query parameter** (`?orderId=`), an
+   **RPC method** (XRPC `/xrpc/…getRecord`, tRPC `user.byId`), or a **GraphQL
+   field** (`user(id: ID!)`) — and
+2. it **reaches a datastore** — a DB hint in the same file/module, a taint chain
+   from the route to a SQL execute sink, or (for RPC/GraphQL) an object-access
+   operation, and
 3. **no ownership/authorization check** is visible near the handler
-   (`current_user`, `request.user`, `authorize`, a policy/guard, or a
-   `filter_by(user_id=…)`-style scoped query).
+   (`current_user`, `request.user`, `authorize`, a policy/guard, a
+   `filter_by(user_id=…)`-style scoped query, or a GraphQL `@auth`/`@hasRole`
+   schema directive on the field).
 
-Write routes (POST/PUT/PATCH/DELETE) are HIGH, reads MEDIUM. Candidates appear
-under `scan.authz_candidates`; the ownership-marker scan is the main
-false-positive reducer, so a well-scoped handler is not flagged. Path-template
-routes today; query-parameter and RPC-method ids are future work.
+Write operations (POST/PUT/PATCH/DELETE, GraphQL mutations) are HIGH, reads
+MEDIUM. Candidates appear under `scan.authz_candidates` (each carrying its
+`surface`); the ownership-marker scan is the main false-positive reducer, so a
+well-scoped handler or an `@auth`-guarded field is not flagged.
 
 ### Anomaly / outlier detection
 
@@ -430,8 +567,27 @@ of the common manifest files:
 | Composer (PHP) | `composer.json` (require + require-dev; platform reqs skipped) |
 
 Each entry appears in `attackmap-report.json` under `scan.dependencies` with
-`{name, version, ecosystem, file, dev}`. Version ranges are kept verbatim
-(`^4.16.0`, `>=2,<3`, `latest`) — this slice does not resolve lockfiles.
+`{name, version, ecosystem, file, dev, resolved, direct, via}`. Manifest ranges
+are kept verbatim (`^4.16.0`, `>=2,<3`, `latest`).
+
+**Lockfile resolution (#143).** When a lockfile is present it is parsed for
+*exact* resolved versions and the full **transitive** tree — where most
+known-vulnerable dependencies actually live. Resolved entries set
+`resolved=true`, mark `direct`/transitive, and carry a `via` resolution path
+(`express > body-parser > qs`). A lockfile supersedes the range-only manifest
+in its **own directory** (so a monorepo's per-service lockfiles don't shadow
+each other).
+
+| Lockfile | Ecosystem |
+|---|---|
+| `package-lock.json` (v1/v2/v3), `pnpm-lock.yaml` | npm |
+| `poetry.lock`, `uv.lock` | PyPI |
+| `Cargo.lock` | Cargo |
+
+Go needs no lockfile pass: `go.mod` already pins exact versions and flags
+`// indirect` (transitive) deps, so it's treated as resolved directly.
+(`go.sum` is a checksum history, not the build list, so it is not used for
+inventory.)
 
 ### CVE cross-reference (opt-in)
 
@@ -452,9 +608,12 @@ attackmap analyze . --cve
   the network.
 - **Offline-tolerant.** If the network's unavailable but the cache is warm,
   cached results still surface; only fresh queries are skipped.
-- **Version resolution is best-effort.** Manifest ranges (`^4.16.0`,
-  `>=2.28,<3`) resolve to a queryable lower-bound; OSV does the range math.
-  Unpinned specs (`*`, `latest`) are skipped.
+- **Exact when a lockfile exists.** Lockfile-resolved dependencies (direct and
+  transitive) are queried at their pinned version, and a vulnerable transitive
+  dep is reported with its resolution path. For range-only manifests with no
+  lockfile, version resolution is best-effort — ranges (`^4.16.0`, `>=2.28,<3`)
+  resolve to a queryable lower-bound and OSV does the range math; unpinned specs
+  (`*`, `latest`) are skipped.
 
 The structured vulnerability list is available under
 `scan.vulnerabilities` in `attackmap-report.json` with
@@ -508,6 +667,14 @@ a human must verify. Uses the same auth/backend resolution as `--llm`.
 Layered on top: **MITRE ATT&CK technique mappings** on every insight and
 **detection opportunities** (Sigma/KQL/Splunk-style hints) for each weakness.
 
+**6. Triage (`--triage`).** Where `--hunt` finds *new* leads, `--triage`
+distills the *existing* heuristic findings: `attackmap analyze . --triage` has
+the LLM cluster them by root cause, de-duplicate, and rank into a prioritized
+shortlist that cites real finding IDs (it organizes, it never invents). Output
+goes to `triage.md`. When no LLM backend is available it degrades to a
+**deterministic**, score-ordered, clustered shortlist — reproducible enough to
+diff across runs — rather than erroring.
+
 ---
 
 ## Supported ecosystems
@@ -556,12 +723,17 @@ attackmap analyze <path> --llm --llm-provider openai --llm-model gpt-5.5   # any
 attackmap analyze <path> --hunt          # LLM vulnerability-hypothesis hunt (leads to confirm)
 attackmap analyze <path> --hunt --verify # adjudicate each lead vs. source (confirmed/refuted/review)
 attackmap analyze <path> --remediate     # LLM review-first fix suggestions (remediation.md)
+attackmap analyze <path> --triage        # cluster/dedupe/rank existing findings (triage.md; deterministic fallback)
 attackmap analyze <path> --pr-comment pr.md   # Markdown PR summary comment for CI
 
 # CI / PR diff gating
 attackmap analyze <path> --baseline prev/attackmap-report.json \
   --diff-output reports/attackmap-diff.md --fail-on-new-high
 
+# Suppression (.attackmap-suppress.yaml + inline `attackmap:ignore` directives)
+attackmap analyze <path> --no-suppress          # full audit, ignore all suppressions
+attackmap analyze <path> --suppress-file cfg.yaml   # override baseline location
+
 # Plugin discovery
 attackmap suggest ./repo                 # recommend plugins for a repo shape
 attackmap suggest ./repo --install       # and pip-install the missing ones
@@ -585,9 +757,10 @@ introduces a new HIGH finding.
   Dependabot go deeper on transitive resolution and lockfiles. AttackMap's
   value is folding the CVE signal into an architecture-aware narrative
   ("this public route reaches this vulnerable ORM").
-- **A true taint engine.** The data-flow pass is a heuristic import-graph walk
-  (import-edge ≈ call-edge), not sound interprocedural taint analysis. It
-  favors precision over recall; findings are evidence, not proof.
+- **A true taint engine.** The data-flow pass is a heuristic call-graph-refined
+  import-graph walk (edges pruned to used symbols, but symbol *use* ≉ a proven
+  data-carrying call), not sound interprocedural taint analysis. It favors
+  precision over recall; findings are evidence, not proof.
 - **Exhaustive.** AttackMap is heuristic by design. Findings are confidence-tiered
   with explicit guardrails for stale signals.
 
@@ -595,7 +768,7 @@ introduces a new HIGH finding.
 
 ## Project status
 
-AttackMap is **beta** (v0.4.0) — published and validated on real codebases, but
+AttackMap is **beta** (v0.4.15) — published and validated on real codebases, but
 pre-1.0 and heuristic.
 
 **Solid today:**
@@ -617,8 +790,9 @@ pre-1.0 and heuristic.
   explainable 0–100 "exploitable now" score that ranks route→sink combinations
   and folds in known-vulnerable dependencies on the path.
 - **`--hunt`** (LLM exploit-chain hypotheses) with **`--verify`** (adjudicate
-  each lead CONFIRMED/REFUTED/NEEDS-REVIEW against the actual source), and
-  **`--remediate`** (review-first fix suggestions).
+  each lead CONFIRMED/REFUTED/NEEDS-REVIEW against the actual source),
+  **`--remediate`** (review-first fix suggestions), and **`--triage`**
+  (cluster/dedupe/rank existing findings, with a deterministic fallback).
 - SBOM inventory (5 ecosystems) + OSV.dev CVE cross-reference (`--cve`).
 - Output: Markdown + JSON + **SARIF 2.1.0** + **Mermaid / Graphviz** diagrams;
   **diff/baseline** PR gating; a reusable **GitHub Action + PR bot**; optional
@@ -630,11 +804,16 @@ pre-1.0 and heuristic.
 
 **Still maturing:**
 
-- Taint is Python/JS/TS/Go/PHP and path-template scoped; query-param / RPC-method
-  authorization and more languages are planned.
-- The import-graph taint walk approximates call-edges with import-edges — precision
+- BOLA/IDOR authorization now covers path templates, query parameters, RPC
+  methods (XRPC/tRPC), and GraphQL fields; deeper resolver-level GraphQL
+  ownership analysis and more languages are planned.
+- The taint walk is call-graph-aware for Python/JS/TS (import edges are pruned to
+  symbols actually used in the file) but still approximates: symbol *use* is not a
+  proven data-carrying call, and Go/PHP keep the plain import-graph. Precision
   over recall; findings are evidence, not proof.
-- CVE lookup resolves a best-effort concrete version, not full lockfile ranges.
+- CVE lookup uses exact lockfile-resolved versions (direct + transitive) when a
+  lockfile is present; range-only manifests without a lockfile still fall back to
+  a best-effort concrete version.
 - Anomaly / exploitability reasoning is route-cohort and taint-chain scoped.
 
 ---