# CLAUDE.md
Guidance for Claude (and humans) working in this repository.
## What Killer is
Killer is a Rust security platform with two halves:
- **Static analysis** (`killer scan`) — walks a project, detects languages, runs
security/quality rules, prints a scored report.
- **A security test framework** (`killer test`) — runs the **`.klr`** DSL
(Killer Rule Language): `suite`/`test`/`repeat`/`mutate` blocks that describe
attacks and static code rules, executed against a target in parallel.
Plus: project intelligence (`history`), code review over a git diff (`review`),
a CI gate (`ci` / `github enable`), a health check (`doctor`), and
`explain`/`report`/`init` helpers.
Single Cargo crate exposing a **library** (`src/lib.rs`) + a thin **binary**
(`src/main.rs`). Everything testable lives in the library.
**Current status: v1.4.0, released and usable** — builds from source and passes
its full test suite (129 tests, per CI). It is **published on crates.io**, so
installation is `cargo install killer` (or `cargo install --path .` from a
checkout). The whole implementation is on the public `main` branch. See
`CHANGELOG.md` for what shipped and the README roadmap for what's deferred.
## Build & test — READ THIS FIRST (no local toolchain)
**As of 2026-08-02 this machine has no Rust toolchain at all.** `cargo`, `rustc`
and `rustup` are absent, and the Docker daemon is usually stopped, so nothing
here can be compiled or tested locally.
**CI is the compiler.** Push and read the errors out of the run log. Expect two
or three red runs before green, and do not promise a verified build you did not
run. Pull the `cargo fmt --check` diff from the log rather than guessing at
formatting, and edit `Cargo.lock` by hand when bumping a version, since there is
no cargo to regenerate it.
This section previously documented a rustup plus WinLibs MinGW setup with PATH
incantations to work around a missing linker. That toolchain is gone. Check
`Get-Command cargo` before spending any time on it.
On a machine that does have Rust, the usual checks apply:
```sh
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test
```
### Standard checks (run before finishing any change)
```
cargo fmt # then `cargo fmt --check` should be clean
cargo clippy --all-targets # keep it warning-free
cargo test # unit + integration + doc tests
```
## Architecture (module map)
```
src/
├── main.rs # CLI dispatch (scan/test/fuzz/dependencies/compliance/graph/benchmark/watch/report/history/review/ci/github/explain/init/doctor/version)
├── cli.rs # clap definitions
├── lib.rs # public library surface
├── scanner.rs # dir walk, language detection, FileData/ProjectStats
├── fuzz.rs # fuzz generator catalog (shared with .klr) + `killer fuzz` driver
├── graph.rs # structural project graph: imports + declared deps (`killer graph`)
├── dependencies.rs# dependency intelligence across 6 ecosystems (`killer dependencies`)
├── compliance.rs # OWASP/CWE mapping (`killer compliance`; data in ../mappings/compliance.toml)
├── watch.rs # dependency-free polling watcher (`killer watch`)
├── analyzer.rs # Rule trait, Finding/Severity/Category, the Analyzer
├── report.rs # ALL terminal + HTML rendering (scan/test/review/history/banner)
├── results.rs # TestRun/AttackOutcome + JSON persistence (.killer/results)
├── intelligence.rs# score-history snapshots + trend (.killer/history)
├── git.rs # `git diff` parsing for review
├── review.rs # code review over changed lines (+ concurrency heuristics)
├── ci.rs # CI gate helpers + GitHub Actions workflow text
├── explain.rs # knowledge base for `killer explain <ISSUE_ID>`
├── config.rs # .killer.toml loading
├── suites.rs # built-in suites, embedded from ../suites/*.klr via include_str!
├── rules/ # static scan rules (security.rs, quality.rs, dependencies.rs)
├── attacks/ # http.rs (zero-dep client behind HttpClient trait), filesystem.rs, database.rs
└── klr/ # the .klr language
├── lexer.rs parser.rs ast.rs
├── interpreter.rs # runs ONE attack -> AttackOutcome
├── runner.rs # check/mutate expansion + parallel (thread::scope) execution
└── rule_engine.rs # static .klr rules over source
```
## Conventions
- **Zero heavy runtime deps.** The HTTP client is hand-rolled on `std::net`
(http:// only) behind the `HttpClient` trait; storage is JSON files, not a DB.
This is deliberate — it keeps the build portable on the broken toolchain
above. Don't add `reqwest`/`tokio`/`rusqlite` without a very good reason.
- **Tests live next to the code** (`#[cfg(test)] mod tests`) plus integration
suites in `tests/`. `tests/klr_e2e.rs` stands up a real TCP server.
- **Match surrounding style**: doc comments on public items, `anyhow` for
binary-level errors, typed errors (`ParseError`, `HttpError`) in the library.
- **Extension points**: a new scan rule = implement `Rule` + register in
`rules/mod.rs`; a new `.klr` construct = AST + parser + an interpreter arm; a
new transport = implement `HttpClient`.
## Honesty policy (important)
The specs Killer was built from are platform-scale; each phase shipped a real,
tested subset and **explicitly deferred** the rest rather than stubbing it.
Keep that up: don't claim capabilities that aren't implemented and tested.
Input **fuzzing exists** as the `.klr` `mutate`/`fuzz` generators, now also
surfaced by **`killer fuzz`** (preview inputs, or fire them at a target and flag
5xx faults). **`killer watch`** (dependency-free polling) and **`killer graph`**
(a *structural* import/dependency graph with heuristic usage matching) also
ship. **`killer dependencies`** is manifest-only inventory (6 ecosystems, no
CVE/advisory data) and **`killer compliance`** maps detected findings to OWASP
Top 10/CWE (not a certified audit). Still **deferred** (roadmap, not built —
don't advertise as shipped): TLS for attacking `https://` targets, a *semantic*
data-flow graph, Tree-sitter multi-language IR, a coverage-guided fuzzing
engine, a vulnerability/CVE dataset + supply-chain/typosquatting signals for
dependency scanning, certified compliance frameworks (SOC2/ISO/NIST), chaos
testing as its own subsystem, an interactive `ratatui` TUI (`killer ui`), a
plugin SDK, and a networked package manager/marketplace (`killer install`; the "standard library"
is just the built-in embedded suites — six of them: web, api, authentication,
database, crypto, filesystem). A multi-crate workspace is intentionally NOT
done — keep the single crate (rationale in `docs/architecture.md`).
## Repo / website — where everything stands
Use the `martin-k-m` org everywhere. Two public repos, both with the
implementation on `main`. The **tool** is released at **v1.4.0**; keep the
**website** (`killer-web`) synced to the same version (see the cross-repo
obligation below):
**Tool — `github.com/martin-k-m/killer`** (this repo)
- `main` has the full implementation (tagged `v1.0.0` … `v1.4.0`). Local work
happens on branch `claude/killer-phase-1-core-81f540`; the workflow so far has
been: commit on the branch, push the branch, then `git push origin HEAD:main`
(fast-forward), and tag `vX.Y.Z` to fire the release pipeline.
- CI runs on push/PR (`.github/workflows/ci.yml`: fmt, clippy `-D warnings`,
test, cargo audit). Tagging `v*` runs `release.yml` (cross-platform binaries +
GitHub Release with notes from `CHANGELOG.md`).
- OSS files present: README (with badges), CHANGELOG, CONTRIBUTING, SECURITY,
CODE_OF_CONDUCT, GOVERNANCE, SUPPORT, issue/PR templates, and `docs/` (9
guides). Keep these in sync when the CLI/`.klr`/features change.
**Website — sibling repo `killer-web`** (Next.js 16, static export)
- Location on this machine: `C:\Users\comma\Documents\Github\killer-web` (a
sibling of the killer repo, NOT inside a worktree). Deployed to
GitHub Pages (no longer deployed; `docs/` is authoritative)
(`.github/workflows/deploy.yml`; `public/CNAME` holds the domain). Node is at
`C:\Program Files\nodejs` (not on the shell PATH by default).
- `lib/site.ts` is the **content source of truth** and carries an accuracy rule:
every claim must be verifiable against what's on the tool repo's `main`. The
roadmap array there drives the on-site roadmap + progress bar; mark an item
`Shipped` only once its code is public. The site is framed as **released /
"available now · v1.4.0"** and now on crates.io (`cargo install killer`).
- Favicon is `app/icon.svg`; HTTPS metadata (metadataBase/canonical/OG) points
at the https domain. Verify with `npm run build` before pushing.
**Cross-repo sync obligation:** when a CLI command, `.klr` construct, or feature
changes in the tool, update BOTH the tool docs (README, `docs/`, CHANGELOG) AND
`killer-web` (`lib/site.ts`, and the demo components `KLRDemo`/`TerminalDemo`/
`DocumentationPreview` which mirror real CLI output). Push tool changes to
`main` first so the site's claims stay verifiable.
Killer is **published on crates.io** (`cargo install killer`). The
`CARGO_REGISTRY_TOKEN` secret is configured, so the release workflow's
`publish-crate` job publishes automatically on each `vX.Y.Z` tag. It also runs on
a manual `workflow_dispatch`, so a publish can be retried without re-tagging, and
it still skips cleanly in a fork where the secret is absent.
**Not done via git (needs the maintainer / GitHub UI):** setting the repo
description & topics, creating the GitHub Release from a tag if the workflow
didn't, and an open Dependabot alert on `killer-web`. Note that Pages settings
no longer apply: `killer-web` is not deployed, and `docs/` is authoritative.