@arsh342/athena 0.3.1 → 0.4.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 CHANGED
@@ -34,6 +34,8 @@ Running `athena` with no arguments opens an interactive menu.
34
34
  | `review` | Review a change: `--staged` (default), `--uncommitted`, `--range a..b`, `--base main`. Only findings on changed lines block. |
35
35
  | `explain <id>` | Explain a finding from the last scan. |
36
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). |
37
39
  | `variants <id> [--save]` | Turn a confirmed finding into a rule and find its look-alikes. |
38
40
  | `skills list\|show\|new\|test\|add\|remove` | Work with skills (see below). |
39
41
  | `keys set\|status\|remove <provider>` | Manage API keys for the optional AI layer. |
@@ -56,6 +58,7 @@ Running `athena` with no arguments opens an interactive menu.
56
58
  | `-m, --max-findings <n\|all>`, `--show-low` | Control how many findings are listed. |
57
59
  | `--no-eslint` | Skip the optional ESLint scanner. |
58
60
  | `--no-deps` | Skip dependency checks. |
61
+ | `--no-learning` | Do not train on or apply this repository's trusted labels (also `"learning": false` in the project config). |
59
62
  | `--offline` | Dependency checks use only cached data (a cold cache is reported as a gap). |
60
63
 
61
64
  Deprecated and ignored: `--no-semgrep`, `--no-nodejsscan`, `--no-bearer`, `--no-npm-audit` (those tools were retired), and `-t, --threshold`.
@@ -96,13 +99,19 @@ Keys come from the environment, then `~/.athena/credentials.json` (mode 0600), a
96
99
 
97
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.
98
101
 
102
+ ## Local learning
103
+
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`.
105
+
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.
107
+
99
108
  ## What Athena checks
100
109
 
101
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.
102
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.
103
112
  - **Secrets:** 60+ provider formats, connection strings and private keys in source and config files. Findings never contain the secret.
104
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".
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.
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).
106
115
 
107
116
  Syntax-error files are reported as `parse-failed` in coverage and their readable parts are still analyzed.
108
117