@arsh342/athena 0.3.0 → 0.3.1
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 +83 -144
- package/dist/index.cjs +69886 -11077
- package/package.json +13 -6
package/README.md
CHANGED
|
@@ -1,63 +1,53 @@
|
|
|
1
1
|
# Athena CLI
|
|
2
2
|
|
|
3
|
-
AI
|
|
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
|
-
|
|
10
|
-
npm install -g @arsh342/athena
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Quick Start
|
|
14
|
-
|
|
15
|
-
Open interactive selector:
|
|
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.
|
|
16
8
|
|
|
17
9
|
```bash
|
|
18
|
-
athena
|
|
19
|
-
# or
|
|
20
|
-
athena
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Scan current directory:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
athena scan .
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Check staged files (what the pre-commit hook runs):
|
|
30
|
-
|
|
31
|
-
```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
|
-
|
|
15
|
+
## Quick start
|
|
44
16
|
|
|
45
17
|
```bash
|
|
46
|
-
athena
|
|
47
|
-
athena
|
|
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
|
-
|
|
26
|
+
Running `athena` with no arguments opens an interactive menu.
|
|
51
27
|
|
|
52
|
-
|
|
53
|
-
athena setup all
|
|
54
|
-
```
|
|
28
|
+
## Commands
|
|
55
29
|
|
|
56
|
-
|
|
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
|
+
| `variants <id> [--save]` | Turn a confirmed finding into a rule and find its look-alikes. |
|
|
38
|
+
| `skills list\|show\|new\|test\|add\|remove` | Work with skills (see below). |
|
|
39
|
+
| `keys set\|status\|remove <provider>` | Manage API keys for the optional AI layer. |
|
|
40
|
+
| `mcp` | Serve Athena's tools to MCP clients over stdio. |
|
|
41
|
+
| `update` | Refresh advisory data and signed rule packs (`--rollback` restores the previous pack). |
|
|
42
|
+
| `alerts` | New vulnerabilities since your last scan (exit 1 if any). |
|
|
43
|
+
| `init` / `uninstall` | Install or remove git hooks (`init --hooks pre-commit,pre-push`). |
|
|
44
|
+
| `setup`, `doctor`, `menu` | Configuration, health check, interactive menu. |
|
|
45
|
+
|
|
46
|
+
## Options (scan, check and review)
|
|
57
47
|
|
|
58
48
|
| Flag | Meaning |
|
|
59
49
|
|---|---|
|
|
60
|
-
| `-f, --format <terminal\|json\|jsonl\|sarif>` | Output format. `json` and `sarif` print only that document on stdout. |
|
|
50
|
+
| `-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
51
|
| `-o, --output <file>` | Write the report to a file instead of stdout. |
|
|
62
52
|
| `--fail-on <critical\|high\|medium\|low\|none>` | Block on findings at or above this level (default `high`). |
|
|
63
53
|
| `--strict` | Exit 3 when the scan was incomplete (files or checks skipped). |
|
|
@@ -65,13 +55,10 @@ athena setup all
|
|
|
65
55
|
| `--no-color` | Disable colour (also off for `NO_COLOR` and non-TTY output). |
|
|
66
56
|
| `-m, --max-findings <n\|all>`, `--show-low` | Control how many findings are listed. |
|
|
67
57
|
| `--no-eslint` | Skip the optional ESLint scanner. |
|
|
68
|
-
| `--no-semgrep`, `--no-nodejsscan`, `--no-bearer` | Deprecated, do nothing (those scanners were retired). |
|
|
69
58
|
| `--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. |
|
|
72
59
|
| `--offline` | Dependency checks use only cached data (a cold cache is reported as a gap). |
|
|
73
|
-
|
|
74
|
-
|
|
60
|
+
|
|
61
|
+
Deprecated and ignored: `--no-semgrep`, `--no-nodejsscan`, `--no-bearer`, `--no-npm-audit` (those tools were retired), and `-t, --threshold`.
|
|
75
62
|
|
|
76
63
|
## Exit codes
|
|
77
64
|
|
|
@@ -84,130 +71,82 @@ athena setup all
|
|
|
84
71
|
|
|
85
72
|
Blocked wins over incomplete.
|
|
86
73
|
|
|
87
|
-
##
|
|
74
|
+
## Optional AI layer
|
|
88
75
|
|
|
89
|
-
|
|
76
|
+
Off unless you pass `--ai`. It only checks what the offline analyzers were unsure about, with your own key and a hard spend cap.
|
|
90
77
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
78
|
+
| Flag | Meaning |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `--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`. |
|
|
81
|
+
| `--provider <name>` | `anthropic` (default), `openai`, `google`, `openai-compatible`. |
|
|
82
|
+
| `--model <id>` | Model to use. Anthropic default is `claude-sonnet-5-5`; other providers need `--model`. |
|
|
83
|
+
| `--quality <economy\|high>` | Anthropic only: Haiku 5.5 or Opus 5.5 instead of Sonnet 5.5. |
|
|
84
|
+
| `--budget <usd>`, `--budget-tokens <n>` | Spend cap for this run (default $0.25 per run, $1.00 per day). Deep mode requires one. |
|
|
85
|
+
| `--preset <name>`, `--base-url <url>` | For openai-compatible: `openrouter`, `deepseek`, `mistral`, `groq`, `xai`, `together`, `ollama`, `lmstudio`, or an https endpoint. |
|
|
86
|
+
| `--suggest-fixes` | With `deep`: write reviewed patch suggestions to `.athena/patches/`. They are never applied. |
|
|
87
|
+
| `-y, --yes` | Agree to send code excerpts without asking (needed for non-interactive runs). |
|
|
96
88
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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 |
|
|
89
|
+
```bash
|
|
90
|
+
athena keys set anthropic
|
|
91
|
+
athena scan . --ai verify
|
|
92
|
+
athena scan . --ai deep --budget 1 --suggest-fixes
|
|
93
|
+
```
|
|
108
94
|
|
|
109
|
-
|
|
95
|
+
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.
|
|
110
96
|
|
|
111
|
-
The
|
|
97
|
+
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.
|
|
112
98
|
|
|
113
99
|
## What Athena checks
|
|
114
100
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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. |
|
|
101
|
+
- **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.
|
|
102
|
+
- **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.
|
|
103
|
+
- **Secrets:** 60+ provider formats, connection strings and private keys in source and config files. Findings never contain the secret.
|
|
104
|
+
- **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".
|
|
105
|
+
- **AI provenance:** lines credited to AI tools in git history (a floor) plus a style-based estimate, shown as a range with its method. No language yet meets the release targets for the trained detector, so estimates say they are heuristic.
|
|
131
106
|
|
|
132
|
-
|
|
107
|
+
Syntax-error files are reported as `parse-failed` in coverage and their readable parts are still analyzed.
|
|
133
108
|
|
|
134
|
-
##
|
|
135
|
-
|
|
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.
|
|
137
|
-
|
|
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 |
|
|
109
|
+
## Supported languages
|
|
143
110
|
|
|
144
|
-
|
|
111
|
+
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
112
|
|
|
146
|
-
|
|
113
|
+
## Skills
|
|
147
114
|
|
|
148
|
-
|
|
115
|
+
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
116
|
|
|
150
|
-
|
|
117
|
+
```bash
|
|
118
|
+
athena skills list # what is active for this project
|
|
119
|
+
athena skills show express
|
|
120
|
+
athena skills new my-skill # scaffold with fixtures (repo: .athena/skills/)
|
|
121
|
+
athena skills test
|
|
122
|
+
athena skills add <git-url>[#subdir][@commit]
|
|
123
|
+
```
|
|
151
124
|
|
|
152
|
-
|
|
125
|
+
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
126
|
|
|
154
|
-
##
|
|
127
|
+
## Git gates, MCP and the Claude Code plugin
|
|
155
128
|
|
|
156
|
-
-
|
|
157
|
-
- **
|
|
158
|
-
- **
|
|
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.
|
|
129
|
+
- **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.
|
|
130
|
+
- **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.
|
|
131
|
+
- **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
132
|
|
|
161
133
|
## Staying current
|
|
162
134
|
|
|
163
|
-
|
|
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.
|
|
135
|
+
`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
136
|
|
|
174
|
-
##
|
|
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
|
-
```
|
|
137
|
+
## Project config
|
|
194
138
|
|
|
195
|
-
|
|
139
|
+
Optional `athena.config.json` at the scanned root. Flags override it.
|
|
196
140
|
|
|
197
|
-
```
|
|
198
|
-
|
|
141
|
+
```json
|
|
142
|
+
{ "failOn": "high", "exclude": ["generated/"], "strict": false, "publicRoutes": ["/health"] }
|
|
199
143
|
```
|
|
200
144
|
|
|
201
|
-
|
|
145
|
+
## Develop
|
|
202
146
|
|
|
203
147
|
```bash
|
|
204
148
|
npm run build -w @arsh342/athena
|
|
149
|
+
npm test -w @arsh342/athena
|
|
205
150
|
```
|
|
206
151
|
|
|
207
|
-
|
|
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.
|
|
152
|
+
MIT licence. More: [project README](https://github.com/arsh342/athena#readme).
|