Taskfile.yml

# Taskfile — one task runner across the polyglot repo (https://taskfile.dev).
# `task` shows all tasks; per-component verify + an aggregate `task ci` mirroring the pipeline.

version: "3"

tasks:
  default:
    cmds: ["task --list"]

  headers:
    desc: Enforce the 2-line file-header convention
    cmds: ["python3 scripts/check_headers.py"]

  hooks:
    desc: Install the local git pre-commit hook (ruff lint + format + headers gate)
    cmds:
      - git config core.hooksPath .githooks
      - 'echo "pre-commit hook installed → .githooks/pre-commit (ruff check + ruff format --check + headers)"'

  verify-deployed:
    desc: "Check the LIVE detector matches the committed ruleset/prior — catch a stale deploy (a fix not in effect)"
    cmds:
      - bash scripts/verify_deployed.sh

  contracts:
    desc: Validate JSON-Schema contracts + examples + the rule registry
    dir: detector
    cmds: ["uv run python -c 'from kitsune_detector.contracts import load_rule_registry; load_rule_registry(); print(\"contracts ok\")'"]

  detector:
    desc: Lint, type-check, and test the detector
    dir: detector
    cmds:
      - uv run ruff check .
      - uv run ruff format --check .
      - uv run mypy
      - uv run pytest

  harness:
    desc: Lint, type-check, and test the harness
    dir: harness
    cmds:
      - uv run ruff check .
      - uv run ruff format --check .
      - uv run mypy
      - uv run pytest

  fleet:
    desc: "Lint, type-check, and test Skulk (the fleet adversary-emulation kit)"
    dir: fleet
    cmds:
      - uv run ruff check .
      - uv run ruff format --check .
      - uv run mypy
      - uv run pytest

  edge:
    desc: Vet, build, and test the Go edge
    dir: edge
    cmds:
      - gofmt -l .
      - go vet ./...
      - go test ./... -cover

  collector:
    desc: Type-check, lint, and test the TS collector
    dir: collector
    cmds:
      - pnpm run typecheck
      - pnpm run lint
      - pnpm exec prettier --check .
      - pnpm test

  demo:
    desc: Run the spine scoreboard demo
    dir: harness
    cmds: ["uv run python -m kitsune_harness"]

  calibrate:
    desc: "Measure rule false positives against real browserforge fingerprints (FP report)"
    dir: harness
    cmds: ["uv run --with browserforge python -m kitsune_harness.browserforge_corpus --n {{.N | default 500}}"]

  coordination-eval:
    desc: "Measure the fleet detector's precision/recall across legit + malicious coordination scenarios"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.coordination_scenarios"]

  coordination-live:
    desc: "Run coordination grading against the LIVE detector's session store (set KITSUNE_DETECTOR)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.live_coordination {{.CLI_ARGS}}"]

  coordination-fleet-demo:
    desc: "End-to-end fleet demo: ingest a coordinated fleet into a LIVE detector, then grade it (KITSUNE_DETECTOR)"
    dir: harness
    cmds:
      - uv run python tools/fleet_coordination_demo.py
      - uv run python -m kitsune_harness.live_coordination {{.CLI_ARGS}}

  adversary-showcase:
    desc: "The red⇄blue escalation ladder: emit canonical fleet shapes to a LIVE detector and grade each through BOTH the per-binding scorer and axis A. Spine up; off-network pass --detector http://localhost:8099."
    dir: harness
    cmds:
      - uv run python tools/adversary_showcase.py {{.CLI_ARGS}}

  coordination-fleet-capture:
    desc: "AUTHENTIC live fleet: run N concurrent real evader containers (distinct container IPs) through the edge, then grade the cloned-profile collision. Spine must be up (edge+detector). Env: IMAGE, N (e.g. IMAGE=kitsune-stealth:latest N=3)."
    cmds:
      - OUT=/tmp/ks-fleet bash harness/tools/fleet_capture.sh
      - cd harness && uv run python -m kitsune_harness.coordination /tmp/ks-fleet

  coordination-fleet-manage:
    desc: "Run a MANAGED real-evader fleet from NAMED evasions (mixed, per-node proxy + retry) and grade it. `-- --list-evasions` to see the registry. Spine up; off-network pass --detector http://localhost:8099. e.g. task coordination-fleet-manage -- --evasion camoufox-linux --evasion zendriver-uach --n 2 --detector http://localhost:8099"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.fleet_manager {{.CLI_ARGS}}"]

  archetype-validate:
    desc: "Run EVERY adversary archetype's real fleet against the live detector and check the outcome matches the catalog (turns each persona's `expected` into a tested contract). Spine up; off-network pass --detector http://localhost:8099."
    dir: harness
    cmds: ["uv run python -m kitsune_harness.fleet_manager --validate-archetypes {{.CLI_ARGS}}"]

  scope-rps:
    desc: "Recon: scope a target's request-rate budget (ramp RPS, find the throttle/challenge/saturation knee). Authorized targets only. e.g. task scope-rps -- http://localhost:8099/healthz --rates 1,5,10,25,50,100"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.rps_scout {{.CLI_ARGS}}"]

  calibrate-intoli:
    desc: "Corroborate the calibration against a second real-traffic source (Intoli user-agents dataset)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.intoli_corpus --n {{.N | default 4000}}"]

  prevalence-corroborate:
    desc: "Diff the prevalence prior (gpu/screen/cores) vs fpgen's independent data — single-source overfit check"
    dir: harness
    cmds: ["uv run --with fpgen python -m kitsune_harness.fpgen_corroborate --n {{.N | default 500}}"]

  coherence-corroborate:
    desc: "Second-source FP-check of the font/webgl/platform/productSub coherence rules vs fpgen's data"
    dir: harness
    cmds: ["uv run --with fpgen python -m kitsune_harness.fpgen_coherence --n {{.N | default 400}}"]

  biomech-corroborate:
    desc: "Second-source FP-check of the biomech power-law floor vs SapiMouse (set KITSUNE_SAPIMOUSE_DIR)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.sapimouse_corpus"]

  template-calibrate:
    desc: "Ground the template-similarity floor: in-sandbox humanizer-vs-humans separation + SapiMouse 2nd source (set KITSUNE_SAPIMOUSE_DIR)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.template_calibration"]

  prevalence-real-corroborate:
    desc: "Tier-3: corroborate the prevalence prior vs a REAL-traffic fingerprint CSV (run LOCALLY; raw data not committed)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.prevalence_real_corroborate {{.CLI_ARGS}}"]

  grounding:
    desc: "Grounding sweep over a DIR of real captured sessions: per-session FP/recall + coordination + (--build-prior) prior rebuild. Run LOCALLY on operator data — see docs/grounding.md. e.g. task grounding -- ../corpus/sessions --expect bot"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.grounding {{.CLI_ARGS}}"]

  docs:
    desc: "Regenerate ALL auto-generated docs (README stats, rule + evasion catalogs, evader matrix, scoreboard) from source"
    dir: harness
    cmds:
      - uv run python -m kitsune_harness.readme_stats
      - uv run python -m kitsune_harness.readme_redteam
      - uv run python -m kitsune_harness.rule_catalog
      - uv run python -m kitsune_harness.evasion_catalog
      - task: coordination-catalog
      - uv run python -m kitsune_harness.report ../corpus/sessions > ../docs/matrix.md
      - uv run python -m kitsune_harness.request1_audit --write
      - uv run python -m kitsune_harness > ../docs/scoreboard.md

  docs:check:
    desc: "CI gate: fail if any committed auto-generated doc (README stats, catalogs, matrix) drifted from its source"
    dir: harness
    cmds:
      # The marker-spliced + matrix docs are deterministic (registry/corpus-derived, no timestamps), so a drift
      # is a hard CI failure: regenerate, then git-diff. (scoreboard.md carries a timestamp, so it is regenerated
      # by `task docs` + the Pages deploy but not strictly gated.)
      - uv run python -m kitsune_harness.readme_stats --check
      - uv run python -m kitsune_harness.readme_redteam --check
      - uv run python -m kitsune_harness.rule_catalog --check
      - uv run python -m kitsune_harness.evasion_catalog --check
      - (cd ../fleet && uv run python -m skulk.catalog --check)
      - uv run python -m kitsune_harness.report ../corpus/sessions > ../docs/matrix.md
      - git -C .. diff --exit-code -- docs/matrix.md || (echo "docs/matrix.md is STALE — run 'task docs'" >&2; exit 1)
      - uv run python -m kitsune_harness.request1_audit --write
      - git -C .. diff --exit-code -- docs/request1-audit.md || (echo "docs/request1-audit.md is STALE — run 'task docs'" >&2; exit 1)

  catalog:
    desc: "Regenerate the complete rule registry in docs/detection-catalog.md from contracts/rules/registry.yaml"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.rule_catalog"]

  evasion-catalog:
    desc: "Regenerate the evasion-technique registry in docs/evasion-catalog.md from the evaders + scored corpus"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.evasion_catalog"]

  request1-audit:
    desc: "The request-1 / no-JS separation number: request-1 convicting rule set + real-browser FP rate + evader recall (botwall's core pitch), scored network-only over the committed captures"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.request1_audit --write"]

  coordination-catalog:
    desc: "Regenerate the coordination-strategy ladder in fleet/README.md from the Skulk strategy registry"
    dir: fleet
    cmds: ["uv run python -m skulk.catalog"]

  matrix:
    desc: "Refresh docs/matrix.md from the committed real captures against the current ruleset (no live run)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.report ../corpus/sessions > ../docs/matrix.md"]

  scoreboard:
    desc: "Refresh docs/scoreboard.md from the committed real captures against the current ruleset (no live run)"
    dir: harness
    cmds: ["uv run python -m kitsune_harness.corpus ../corpus/sessions > ../docs/scoreboard.md"]

  ci:
    desc: Run the full local pipeline
    cmds:
      - task: headers
      - task: contracts
      - task: docs:check
      - task: detector
      - task: harness
      - task: fleet
      - task: edge
      - task: collector