@arsh342/athena 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,63 +1,55 @@
1
1
  # Athena CLI
2
2
 
3
- AI code provenance tracker and security scanner for JavaScript/TypeScript, Python, Java, C#, C/C++, Go, Rust, PHP and Shell.
4
-
5
- Athena scans JS/TS/JSX/TSX files, extracts function-level code units, scores AI-origin likelihood with local heuristics, and runs targeted security checks.
3
+ Find out what AI wrote in your repository, and whether it is safe to ship. Athena scans JavaScript/TypeScript, Python, Java, C#, C/C++, Go, Rust, PHP and Shell for security problems and estimates how much of the code was written by AI. It runs offline, needs no account, and works as a CLI, a git hook, an MCP server and a Claude Code plugin.
6
4
 
7
5
  ## Install
8
6
 
9
- ```bash
10
- npm install -g @arsh342/athena
11
- ```
12
-
13
- ## Quick Start
14
-
15
- Open interactive selector:
16
-
17
- ```bash
18
- athena
19
- # or
20
- athena menu
21
- ```
22
-
23
- Scan current directory:
24
-
25
- ```bash
26
- athena scan .
27
- ```
28
-
29
- Check staged files (what the pre-commit hook runs):
7
+ Requires Node.js 18 or newer. The optional ESLint scanner needs Node 20.19 or newer; on older Node it is skipped and Athena's own engine does the work.
30
8
 
31
9
  ```bash
32
- athena check
33
- ```
34
-
35
- Explain one finding from the last scan, and see how much code was AI-written:
36
-
37
- ```bash
38
- athena explain 3f9a2c # id shown in the report (at least 4 characters)
39
- athena provenance . # per-file AI provenance
40
- athena provenance --about # how it is measured
10
+ npm install -g @arsh342/athena
11
+ # or run without installing
12
+ npx @arsh342/athena scan .
41
13
  ```
42
14
 
43
- Install or remove the pre-commit hook:
15
+ ## Quick start
44
16
 
45
17
  ```bash
46
- athena init
47
- athena uninstall
18
+ athena scan . # scan the current project
19
+ athena review # review only your staged changes
20
+ athena explain <finding-id> # why it matters and how to fix it (id from the report, 4+ characters)
21
+ athena provenance . # per-file AI provenance (athena provenance --about explains the method)
22
+ athena init # install the pre-commit hook (athena uninstall removes it)
23
+ athena doctor # check Node, npm, git and ESLint
48
24
  ```
49
25
 
50
- See what (if anything) needs installing:
26
+ Running `athena` with no arguments opens an interactive menu.
51
27
 
52
- ```bash
53
- athena setup all
54
- ```
28
+ ## Commands
55
29
 
56
- ## Options (scan and check)
30
+ | Command | What it does |
31
+ |---|---|
32
+ | `scan [path]` | Scan a project. |
33
+ | `check [files]` | Scan staged files (what the pre-commit hook runs). |
34
+ | `review` | Review a change: `--staged` (default), `--uncommitted`, `--range a..b`, `--base main`. Only findings on changed lines block. |
35
+ | `explain <id>` | Explain a finding from the last scan. |
36
+ | `provenance [path]` | How much code looks AI-written, per file. |
37
+ | `provenance mark <file[:line]> <human\|ai\|mixed>` | Tell Athena who wrote a function (stored by code hash). Athena learns from marks. |
38
+ | `models reset [--repo]` | Forget what Athena learned from labels and marks (this repository with `--repo`, otherwise all). |
39
+ | `variants <id> [--save]` | Turn a confirmed finding into a rule and find its look-alikes. |
40
+ | `skills list\|show\|new\|test\|add\|remove` | Work with skills (see below). |
41
+ | `keys set\|status\|remove <provider>` | Manage API keys for the optional AI layer. |
42
+ | `mcp` | Serve Athena's tools to MCP clients over stdio. |
43
+ | `update` | Refresh advisory data and signed rule packs (`--rollback` restores the previous pack). |
44
+ | `alerts` | New vulnerabilities since your last scan (exit 1 if any). |
45
+ | `init` / `uninstall` | Install or remove git hooks (`init --hooks pre-commit,pre-push`). |
46
+ | `setup`, `doctor`, `menu` | Configuration, health check, interactive menu. |
47
+
48
+ ## Options (scan, check and review)
57
49
 
58
50
  | Flag | Meaning |
59
51
  |---|---|
60
- | `-f, --format <terminal\|json\|jsonl\|sarif>` | Output format. `json` and `sarif` print only that document on stdout. |
52
+ | `-f, --format <terminal\|json\|jsonl\|sarif\|markdown\|cyclonedx>` | Output format. `json` and `sarif` print only that document on stdout; `cyclonedx` prints the dependency inventory as a CycloneDX 1.6 SBOM; `markdown` is PR-comment ready. |
61
53
  | `-o, --output <file>` | Write the report to a file instead of stdout. |
62
54
  | `--fail-on <critical\|high\|medium\|low\|none>` | Block on findings at or above this level (default `high`). |
63
55
  | `--strict` | Exit 3 when the scan was incomplete (files or checks skipped). |
@@ -65,13 +57,11 @@ athena setup all
65
57
  | `--no-color` | Disable colour (also off for `NO_COLOR` and non-TTY output). |
66
58
  | `-m, --max-findings <n\|all>`, `--show-low` | Control how many findings are listed. |
67
59
  | `--no-eslint` | Skip the optional ESLint scanner. |
68
- | `--no-semgrep`, `--no-nodejsscan`, `--no-bearer` | Deprecated, do nothing (those scanners were retired). |
69
60
  | `--no-deps` | Skip dependency checks. |
70
- | `--format markdown` | PR-comment-ready output (used by `athena review`). |
71
- | `--format cyclonedx` | Print the dependency inventory as a CycloneDX 1.6 SBOM. |
61
+ | `--no-learning` | Do not train on or apply this repository's trusted labels (also `"learning": false` in the project config). |
72
62
  | `--offline` | Dependency checks use only cached data (a cold cache is reported as a gap). |
73
- | `--no-npm-audit` | Deprecated, does nothing (replaced by dependency checks). |
74
- | `-t, --threshold <n>` | Deprecated: only affects the heuristic AI fallback. |
63
+
64
+ Deprecated and ignored: `--no-semgrep`, `--no-nodejsscan`, `--no-bearer`, `--no-npm-audit` (those tools were retired), and `-t, --threshold`.
75
65
 
76
66
  ## Exit codes
77
67
 
@@ -84,130 +74,88 @@ athena setup all
84
74
 
85
75
  Blocked wins over incomplete.
86
76
 
87
- ## Project config
88
-
89
- Optional `athena.config.json` at the scanned root. Flags override it.
90
-
91
- ```json
92
- { "failOn": "high", "exclude": ["generated/"], "strict": false }
93
- ```
94
-
95
- ## Supported languages
77
+ ## Optional AI layer
96
78
 
97
- | Language | Extensions | Today |
98
- |---|---|---|
99
- | JavaScript / TypeScript (JSX, TSX) | `.js .mjs .cjs .ts .mts .cts .jsx .tsx` | own rules + taint (cross-file), secrets, hallucinated APIs, units, AI provenance, external scanners |
100
- | Python | `.py .pyi`, `#!…python` scripts | own rules + taint, secrets, units, AI provenance |
101
- | Java | `.java` | own rules + taint, secrets, units, AI provenance |
102
- | C# | `.cs` | own rules + taint, secrets, units, AI provenance |
103
- | C / C++ | `.c .h` / `.cc .cpp .cxx .hpp .hh .hxx` | own rules + taint, memory-safety checks, secrets, units, AI provenance (C is parsed with the C++ grammar) |
104
- | Go | `.go` | own rules + taint, secrets, units, AI provenance |
105
- | Rust | `.rs` | own rules + taint, secrets, units, AI provenance |
106
- | PHP | `.php .phtml` | own rules + taint, secrets, units, AI provenance |
107
- | Shell | `.sh .bash .zsh`, `#!…sh/bash/zsh` scripts | own rules + taint, secrets, units, AI provenance |
79
+ Off unless you pass `--ai`. It only checks what the offline analyzers were unsure about, with your own key and a hard spend cap.
108
80
 
109
- Every file is parsed with [tree-sitter](https://tree-sitter.github.io/) (bundled, no install needed). Files with a syntax error are reported as `parse-failed` in coverage and their readable parts are still analyzed. Athena's own rules, taint analysis and secret scanning cover every language above. The optional ESLint scanner covers JavaScript/TypeScript only.
81
+ | Flag | Meaning |
82
+ |---|---|
83
+ | `--ai [verify\|hunt\|deep]` | `verify` (default) settles uncertain findings. `hunt` also explores the riskiest components. `deep` adds a threat model, a three-voter panel and learned rules, and needs `--budget`. |
84
+ | `--provider <name>` | `anthropic` (default), `openai`, `google`, `openai-compatible`. |
85
+ | `--model <id>` | Model to use. Anthropic default is `claude-sonnet-5-5`; other providers need `--model`. |
86
+ | `--quality <economy\|high>` | Anthropic only: Haiku 5.5 or Opus 5.5 instead of Sonnet 5.5. |
87
+ | `--budget <usd>`, `--budget-tokens <n>` | Spend cap for this run (default $0.25 per run, $1.00 per day). Deep mode requires one. |
88
+ | `--preset <name>`, `--base-url <url>` | For openai-compatible: `openrouter`, `deepseek`, `mistral`, `groq`, `xai`, `together`, `ollama`, `lmstudio`, or an https endpoint. |
89
+ | `--suggest-fixes` | With `deep`: write reviewed patch suggestions to `.athena/patches/`. They are never applied. |
90
+ | `-y, --yes` | Agree to send code excerpts without asking (needed for non-interactive runs). |
110
91
 
111
- The report header shows files per language, e.g. `12 files (js 3 · py 2 · go 1)`.
92
+ ```bash
93
+ athena keys set anthropic
94
+ athena scan . --ai verify
95
+ athena scan . --ai deep --budget 1 --suggest-fixes
96
+ ```
112
97
 
113
- ## What Athena checks
98
+ Keys come from the environment, then `~/.athena/credentials.json` (mode 0600), and are never printed or logged. Athena reserves the worst-case cost before every call and stops when the next call could exceed a cap; the report lists what was not checked. The first time in a repository it shows exactly what is sent and asks. Secrets and dependency findings are never sent, and repository text is treated as data, never as instructions. Local models (Ollama, LM Studio) cost nothing and send nothing off your machine.
114
99
 
115
- Athena's own offline engine covers all supported languages: rule packs, taint analysis with source-to-sink paths, 60+ secret formats (also in `.env`, YAML and JSON files), and an investigation engine that finds routes missing the authentication or owner filter their siblings use, validators that never fail, error paths that report success, read-then-write races and more. Each finding carries a confidence; `low` ones appear under **needs review** and never block. Mark routes that are public on purpose in `athena.config.json`: `{ "publicRoutes": ["/health"] }`. See the main README for details.
100
+ The Anthropic and OpenAI SDKs are built in. Google's is large, so it is not installed by default: for `--provider google`, run `npm install -g @google/genai` once.
116
101
 
117
- ## Dependency checks
102
+ ## Local learning
118
103
 
119
- Athena reads every manifest and lockfile it finds (npm, Yarn, pnpm, pip/poetry/uv/Pipenv, Maven/Gradle, NuGet, Go, Cargo, Composer, vcpkg, Conan) and reports, in a separate **Dependencies** section:
104
+ Athena can tune its AI-code estimate to a repository, locally, from trusted labels only: lines git credits to AI-assisted commits (AI), code whose every line was last changed before 2021-06-01 (human), and your own `athena provenance mark` entries. It activates at 30 labels with at least 10 of each class, shifts an estimate by at most 0.25, and is adopted only if it lowers log-loss on a held-out 20% of the labels and does not reduce AI recall or raise the human false-positive rate by more than one point on a bundled check set. State is in `~/.athena/learning/` (mode 0600) and holds hashes and style numbers, never code. A mark applies only while the code is unchanged. The report line reads `learning: tuned with N labels from this repo (changed X of Y units)` or `learning: global model`.
120
105
 
121
- | Finding | Meaning | What to do |
122
- |---|---|---|
123
- | Vulnerable dependency | A known advisory (OSV.dev) affects the exact version. Severity comes from CVSS. If the advisory names the affected functions and your code never imports them, severity drops one level and the report says so. | Upgrade to the fixed version shown. |
124
- | Malicious package | The version is a known malicious release (`MAL-` advisory). | Remove it and rotate any secrets it could read. |
125
- | Package does not exist | A declared dependency, or an import that is declared nowhere, is not on the public registry. Often an AI-invented name that anyone could register. | Fix the name or remove it. |
126
- | Possible typosquat | A direct dependency is one or two edits away from a popular package. | Check you meant the popular one. |
127
- | Deprecated / yanked / abandoned | The registry says so. | Move to a maintained release or alternative. |
128
- | Very new release | Published in the last 72 hours. | Wait out the cooldown or review it. |
129
- | Install script | A direct npm dependency runs `preinstall`/`install`/`postinstall`. | Review it, or install with `--ignore-scripts`. |
130
- | Hallucinated API call | You call a member that the installed package's type declarations do not contain (`axios.fetchData`). Only checked when the package is installed with types. | Use the real API. |
106
+ The trained detector is enabled only for JavaScript so far; every other language uses the style heuristic, which rarely scores near the decision boundary, so tuning there seldom changes a result. The report shows how many units tuning changed.
131
107
 
132
- Private packages (`file:`, `git+`, workspace and scoped-registry packages) are never looked up. A registry outage or rate limit is reported as a coverage gap, never as "does not exist". Answers are cached for 24 hours (advisories 6 hours) under `~/.athena/cache/deps`; `--offline` uses only that cache (and reports the cache date or a gap), and `--no-deps` skips the checks. Athena sends package names and versions to OSV.dev and the package registries, never your code. `npm audit` was replaced by these checks; `--no-npm-audit` is accepted for one release and does nothing.
108
+ ## What Athena checks
133
109
 
134
- ## Optional AI layer (bring your own key)
110
+ - **Code security:** rule packs for injection, path traversal, SSRF, XSS, unsafe deserialization, open redirect, weak crypto, disabled TLS verification, JWT misuse, risky cookies/CORS, ReDoS, mass assignment, memory-unsafe C, `unsafe` Rust/Go and shell pitfalls. Taint analysis follows user input through variables, helpers and (JS/TS and Python) across files, and shows the path.
111
+ - **Investigation:** entry points and their auth guards, sibling comparison (the one route missing the check its neighbours have), intent versus code, lifecycles, error paths and races. Every finding is checked for reachability, defenses and impact; `low` confidence findings are listed as **needs review** and never block.
112
+ - **Secrets:** 60+ provider formats, connection strings and private keys in source and config files. Findings never contain the secret.
113
+ - **Dependencies:** known vulnerabilities (OSV, with CVSS, EPSS and CISA KEV), malicious packages, non-existent packages, typosquats, deprecated or very new releases, install scripts, and hallucinated API calls. Private packages are never looked up, and a registry outage is a coverage gap, not "does not exist".
114
+ - **AI provenance:** lines credited to AI tools in git history (a floor) plus a style-based estimate, shown as a range with its method. The trained detector (`athena-detect-fast`) is enabled for a language only when it meets its release targets on a held-out benchmark (human false-positive rate <= 5%, F1 >= 0.85, and the same false-positive limit on 2022-era human code); today that is JavaScript only, and every other language uses a labelled style heuristic. Results: [docs/athena-bench/RESULTS.md](https://github.com/arsh342/athena/blob/main/docs/athena-bench/RESULTS.md).
135
115
 
136
- Athena is offline by default: no model is called unless you pass `--ai`. The AI layer never replaces the offline analyzers; it only checks what they were unsure about.
116
+ Syntax-error files are reported as `parse-failed` in coverage and their readable parts are still analyzed.
137
117
 
138
- | Mode | What it does | Needs |
139
- |---|---|---|
140
- | `--ai verify` (default for `--ai`) | Reads short excerpts around up to 20 uncertain (medium/low confidence) findings, then confirms (raised to high) or refutes (lowered to "needs review") each, citing the lines it relied on. Secrets and dependency findings are never sent. | a key |
141
- | `--ai hunt` | Also lets a read-only agent explore the 3 riskiest components (exposure, findings, AI-written share) for missed issues; its findings are cited, low confidence, then verified. | a key |
142
- | `--ai deep` | Adds a threat model, per-category research, a three-voter verification panel (2 of 3 decided in code), rules learned from confirmed findings (`.athena/learned-rules.json`, reused by every later offline scan) and, with `--suggest-fixes`, patches written to `.athena/patches/` (second-call reviewed, never applied). | a key, `--budget`, and `--yes` when not interactive |
118
+ ## Supported languages
143
119
 
144
- **Keys and providers.** `athena keys set|status|remove <provider>`; keys come from the environment, then `~/.athena/credentials.json` (mode 0600), and are never printed or logged. Providers: `anthropic` (default model `claude-sonnet-5-5`; `--quality economy|high` selects Haiku or Opus), `openai`, `google`, and OpenAI-compatible endpoints (`--preset openrouter|deepseek|mistral|groq|xai|together|ollama|lmstudio` or `--base-url`). Local endpoints (Ollama, LM Studio) cost nothing and send nothing off your machine. For providers other than Anthropic pass `--model`.
120
+ JavaScript/TypeScript (`.js .mjs .cjs .ts .mts .cts .jsx .tsx`), Python (`.py .pyi`), Java (`.java`), C# (`.cs`), C/C++ (`.c .h .cc .cpp .cxx .hpp .hh .hxx`), Go (`.go`), Rust (`.rs`), PHP (`.php .phtml`) and Shell (`.sh .bash .zsh`, shebang scripts). Everything is parsed with bundled [tree-sitter](https://tree-sitter.github.io/) grammars; nothing extra to install. The ESLint scanner is optional and covers JavaScript/TypeScript only.
145
121
 
146
- **Spend is capped.** Defaults: $0.25 per run and $1.00 per day (`--budget`, `--budget-tokens`, or `ai` settings in `athena.config.json`). Before every call Athena reserves the worst case; when the next call could exceed the cap, it stops and the report lists what was not checked. Spend is recorded in `~/.athena/usage.json`. Deep mode refuses to start without an explicit `--budget`, prints an estimate, and asks you to confirm. Non-interactive deep runs on Anthropic use the Message Batches API.
122
+ ## Skills
147
123
 
148
- **Privacy.** On first use in a repository Athena shows exactly what is sent (short excerpts, the flagged function, its data flow, nearby files) and where, and asks once. Repository text is treated as untrusted: it is delimited, and a verdict is accepted only from structured output, so a comment saying "ignore your instructions" cannot change it.
124
+ A skill is packaged expertise for a framework, language or bug class in the open Agent Skills format (a `SKILL.md` plus declarative `rules.json` and `taint.json`). Athena turns one on only when your project uses it (a dependency or an import), then applies its rules and guidance. 39 are built in: methodology, frameworks, ORMs, languages and deployment files.
149
125
 
150
- **On the website** (Settings, "AI key") you can use your own key for scans too: it is kept in your browser tab only, sent as headers with the one scan, held in memory on the server, and never stored or logged. A spend cap (at most $1.00 per scan) is required, you must accept what will be sent first, only one AI scan runs per user at a time, and only hosted providers are allowed (no local models, no arbitrary endpoints).
126
+ ```bash
127
+ athena skills list # what is active for this project
128
+ athena skills show express
129
+ athena skills new my-skill # scaffold with fixtures (repo: .athena/skills/)
130
+ athena skills test
131
+ athena skills add <git-url>[#subdir][@commit]
132
+ ```
151
133
 
152
- **What it does not do.** It does not run your code, apply any patch, or decide anything the offline analyzers can decide. Provider adapters are checked against the vendor SDK types and fake providers in tests; the benchmark in `bench/ai-verify` measures precision and recall against 14 known snippets and is run on demand because it spends real money.
134
+ Skills are data only and contain no code. Regular expressions are checked before a skill loads and run under a time budget. `athena variants <id> --save` stores a learned rule in `.athena/learned-rules.json`, which every later scan applies.
153
135
 
154
- ## Review, git gates and AI agents
136
+ ## Git gates, MCP and the Claude Code plugin
155
137
 
156
- - **`athena review`** reviews a change instead of the whole repository: `--staged` (default), `--uncommitted`, `--range origin/main..HEAD` or `--base main`. Only findings on changed lines count and block; issues elsewhere in a function you touched are listed separately as existing issues (not counted). Renames are followed, binary files are skipped with a note, and dependency checks run only when a manifest or lockfile changed. Formats: terminal, `json`, `sarif`, and `markdown` (a PR-comment-ready review, one section per file).
157
- - **Git gates.** `athena init` installs a pre-commit hook (`athena check --staged`, about one second on a typical commit); `athena init --hooks pre-commit,pre-push` adds a pre-push hook that reviews `@{u}..HEAD`. Both honour `--fail-on` (or `failOn` in `athena.config.json`) and `core.hooksPath`. Husky, lefthook and the pre-commit framework are detected: Athena prints the snippet to add and changes no file. An existing hook that is not Athena's is never overwritten without `--force`. `ATHENA_SKIP=1 git commit` skips the hooks with a note; a missing Athena or a push-hook timeout never blocks. `athena uninstall` removes only Athena's hooks.
158
- - **MCP server.** `athena mcp` serves Athena's tools over stdio to Claude Code, Cursor, Codex and other MCP clients: scan, check files, review, explain, provenance, dependencies, API existence, codebase map, taint paths, symbol and caller search, skills, and one write tool (`athena_add_learned_rule`, which needs `confirm: true`). Results are compact and paginated, secrets are redacted, paths outside the starting directory are refused, and no AI model is called, so no key is needed. Client setup: `docs/agents/mcp-clients.md`.
159
- - **Claude Code plugin.** `plugins/athena` bundles the MCP server, the `athena-security` skill (map, trace, verify under reachability/defenses/impact), a researcher and a verifier agent, `/athena-scan` and `/athena-review`, and hooks that check each edited file and suggest a review after a commit. The same skill is published in the open Agent Skills format at `skills/athena-security` (`npx skills add arsh342/athena`); add `docs/agents/AGENTS.md` to your repository for other agents.
138
+ - **Hooks.** `athena init` installs a pre-commit hook (`athena check --staged`, about a second on a typical commit); `--hooks pre-commit,pre-push` adds a pre-push review of `@{u}..HEAD`. Husky, lefthook and the pre-commit framework are detected and a snippet is printed instead of changing files. `ATHENA_SKIP=1 git commit` skips the hooks.
139
+ - **MCP server.** `claude mcp add athena -- npx -y @arsh342/athena mcp`. Other clients: [MCP client setup](https://github.com/arsh342/athena/blob/main/docs/agents/mcp-clients.md). No AI model is called and no key is needed.
140
+ - **Claude Code plugin.** Clone the repository and run `claude plugin install ./plugins/athena` for `/athena-scan`, `/athena-review`, the `athena-security` skill, a researcher and a verifier agent, and hooks. Other agents: `npx skills add arsh342/athena`.
160
141
 
161
142
  ## Staying current
162
143
 
163
- - **Advisory data.** `athena update` keeps a local, incrementally updated copy of the OSV vulnerability database (which includes the GitHub Advisory Database) for the ecosystems you use, plus CISA's Known Exploited Vulnerabilities list and FIRST's EPSS scores. The first sync of an ecosystem downloads its full export once (npm is about 220 MB); later syncs fetch only changed records, and withdrawn advisories disappear. Checks then run offline and fast; ecosystems without local data fall back to the OSV API.
164
- - **Known exploited.** Findings for vulnerabilities that are being exploited in the wild are labelled, listed first, and block at any severity (`updates.blockKnownExploited`, default on). EPSS shows the probability of exploitation.
165
- - **Automatic, never in your way.** After a scan, if local data is older than 24 hours (`updates.intervalHours`), a background update starts for ecosystems you already synced; the scan never waits for it, and `--offline` disables it. Data older than 7 days is shown as a coverage gap: `advisory data 9 days old — run athena update`.
166
- - **Rule and skill packs.** `athena update` also fetches the newest signed pack from the project's GitHub releases. A pack is accepted only if its Ed25519 signature and SHA-256 verify, it contains data files only, and every rule passes its own fixtures; otherwise the previous pack stays active. `athena update --rollback` returns to the previous pack. The public key that official packs are verified against ships in the CLI (`PACK_PUBLIC_KEY`); packs are built and signed by the maintainer with `scripts/build-pack.ts`.
167
- - **Alerts.** Each scan stores its dependency inventory. `athena alerts` re-checks the last scan against the current local data and lists vulnerabilities published since (exit 1 if any). `--format cyclonedx` exports the inventory as a CycloneDX 1.6 SBOM. The web dashboard shows "N new vulnerabilities affect <repo> since your last scan" with a re-scan button, from a daily backend job.
168
- - **Privacy.** Syncing downloads public data only; nothing about your code or dependencies is sent. Data sources: OSV.dev (CC-BY 4.0, including the GitHub Advisory Database, CC BY 4.0), CISA KEV, FIRST EPSS.
169
-
170
- ## Skills and variants
171
-
172
- Skills add framework- and domain-specific rules and guidance (39 built in). `athena skills list` shows which ones apply to a project; `athena skills new/test/add/remove` write, prove and install them (data only, pinned to a commit, licence shown). `athena variants <finding-id> [--save]` turns one confirmed finding into a rule and finds its siblings. See the main README for the skill format.
144
+ `athena update` keeps a local, incrementally updated copy of the OSV database for the ecosystems you use, plus CISA KEV and EPSS, and fetches the newest signed rule and skill pack (accepted only if its Ed25519 signature and SHA-256 verify and every rule passes its own fixtures). After a scan, data older than 24 hours is refreshed in the background; `--offline` disables that. Only public data is downloaded; nothing about your code is sent. `athena alerts` re-checks your last scan against current data.
173
145
 
174
- ## How AI-written code is estimated
175
-
176
- `recorded` comes from git history (a floor). `estimated` uses Athena's own detector where it meets the published release targets for that language, and a labelled style heuristic elsewhere. Run `athena provenance --about` to see which languages use which, with benchmark numbers.
177
-
178
- ## What the report tells you
179
-
180
- - **Gate**: `BLOCKED`, `PASS`, or `PASS (incomplete)`. A scan never reads as a plain pass when files could not be parsed, were too large, or a scanner was unavailable.
181
- - **Findings**: grouped by severity with a code frame. Secrets are redacted. LOW findings are collapsed unless `--show-low`.
182
- - **AI provenance** (by lines): *recorded* is what git history credits to AI tools (co-author trailers, agent bot authors). It is a floor, and unavailable outside git or in shallow clones. *estimated* is a style heuristic with no measured accuracy yet, labelled low confidence. Uncertain is shown separately.
183
- - **Coverage**: which files and checks ran, and what was skipped.
184
-
185
- Results go to stdout; progress and warnings go to stderr, so `athena scan --format json | jq .` works.
186
-
187
- ## Development
188
-
189
- Run from source:
190
-
191
- ```bash
192
- npm run dev -w @arsh342/athena -- menu
193
- ```
146
+ ## Project config
194
147
 
195
- Quiet npm wrapper output:
148
+ Optional `athena.config.json` at the scanned root. Flags override it.
196
149
 
197
- ```bash
198
- npm run -s dev -w @arsh342/athena -- menu
150
+ ```json
151
+ { "failOn": "high", "exclude": ["generated/"], "strict": false, "publicRoutes": ["/health"] }
199
152
  ```
200
153
 
201
- Build:
154
+ ## Develop
202
155
 
203
156
  ```bash
204
157
  npm run build -w @arsh342/athena
158
+ npm test -w @arsh342/athena
205
159
  ```
206
160
 
207
- ## Notes
208
-
209
- - Runs fully local (no external AI service required).
210
- - Supports JavaScript/TypeScript (JSX, TSX), Python, Java, C#, C/C++, Go, Rust, PHP and Shell (see Supported languages).
211
- - Requires Node.js 18 or newer.
212
- - ESLint scanner support is included via optional package dependencies.
213
- - Semgrep, NodeJSScan and Bearer were retired; nothing external is needed.
161
+ MIT licence. More: [project README](https://github.com/arsh342/athena#readme).