Skip to content

roadmap.md

Latest commit

 

History

History
206 lines (162 loc) · 9.02 KB

roadmap.md

File metadata and controls

206 lines (162 loc) · 9.02 KB
Raw

Roadmap

A roadmap that actually gets this finished (instead of “infinite personal project”).

Phase 0 — Non-negotiables (setup + guardrails)

  • Decide engine mode: Hybrid (use local gitleaks if present, fallback to Docker with warning).
  • Implement config loader (~/.config/tien/config.yaml) + flag overrides.
  • Implement strict safety defaults for URL scanning:
    • Exact-host, scoped, expiring DNS TXT authorization with a required 256-bit challenge
    • All-or-nothing authorization preflight before workers, requests, and cache access
    • Limit url-scan to built-in GET/HEAD checks and fail closed for public URL plugins
    • Localhost/private-IP access disabled by default and private DNS restricted to an exact hostname allowlist, HTTPS transport, DNS TXT authorization, and pinned addresses
    • SSRF and DNS-rebinding protection plus same-origin redirect enforcement
    • Configurable resource budgets for timeout, response body, redirects, retries, and concurrency
    • No arbitrary target-count, finding-count, or default repository file-size caps
  • Define stable enums: severity, confidence, source, category.

Exit criteria: you can run tien --help, load config, and URL scan won’t run on random public targets by accident.

Phase 1 — Core pipeline (foundation)

  • Finalize Finding schema (repo+url single format)
  • Implement deterministic fingerprint generation + dedup strategy
  • Implement storage:
    • gob writer/reader (default)
    • jsonl writer/reader (debug)
  • Implement tien merge (merge + dedup + stable ordering)
  • Implement tien report --type text (minimum useful output)
  • Implement tien encode --to jsonl (conversion)

Exit criteria: scan → merge → report works end-to-end with stable output ordering.

Phase 2 — URL scan (passive, useful, low-noise)

  • Implement input handling:
    • stdin targets
    • --targets file
    • normalize/validate URLs
  • Implement fetcher:
    • HEAD preferred; fallback to GET when needed
    • redirect handling (bounded)
    • timeouts, size limits, concurrency worker pool
  • Implement checks (passive-only):
    • TLS: cert validity/expiry, HTTPS posture, downgrade signals
    • Headers: HSTS, CSP presence/basic pitfalls, XCTO, Referrer-Policy, Permissions-Policy, frame protections
    • Cookies: Secure/HttpOnly/SameSite when Set-Cookie present
    • CORS: wildcard + credentials patterns, permissive origins patterns
    • /.well-known/security.txt existence and basic parsing
    • Mixed content: bounded HTML parse for http:// assets on https pages
  • Implement host summary output (counts by severity + top issues)

Exit criteria: scanning 500–5,000 URLs completes without memory spikes and produces actionable misconfig findings.

Phase 3 — Repo scan (JS/TS-first) with real engines

Start with one engine, then integrate the rest cleanly.

3.1 Secrets (highest ROI)

  • Integrate gitleaks runner
  • Parse output → normalize findings
  • Redact evidence by default (avoid leaking secrets in reports)

Exit criteria: catches common secret leaks with clean, readable findings.

3.2 Dependencies (SCA)

  • Integrate osv-scanner
  • Support npm/yarn/pnpm lockfiles
  • Normalize package+version+advisory into stable fingerprints

Exit criteria: shows vulnerable deps with clear remediation (upgrade to X).

3.3 SAST (JS/TS rules)

  • Integrate semgrep
  • Default ruleset appropriate for JS/TS (configurable)
  • Normalize file+line+rule into stable fingerprints

Exit criteria: flags real insecure patterns without drowning you in garbage.

Phase 4 — Reporting that doesn’t suck

  • tien report --type md (copy/paste into PR/issue)
  • tien report --type sarif (CI / code scanning integration)
  • Grouping options:
    • by source (repo/url)
    • by severity
    • by target (domain or file path)
  • Add --min-severity filter and --only-tags filter
  • Add “Top N” summary + totals table

Exit criteria: you can generate one report that is readable and prioritized.

Phase 5 — Plot (HTML) + run history

  • tien plot generates a single self-contained HTML report
  • Visuals:
    • severity distribution
    • findings over time (by timestamp)
    • top recurring fingerprints
  • Optional: store a local run index (sqlite/json) to view history

Exit criteria: you can open report.html and instantly see what matters.

Phase 6 — Diff + caching (this is where it becomes “daily usable”)

  • tien diff old.tien new.tien:
    • new findings
    • fixed findings
    • changed severity/confidence
  • Repo caching:
    • cache key = (commit hash + config hash + engines versions)
    • skip unchanged scans fast
  • URL caching (optional):
    • ETag/Last-Modified based revalidation for lightweight refreshes

Exit criteria: you can run it on every commit and only see deltas.

Phase 7 — Local scale & reliability

  • Shard mode for URL scanning:
    • --shard 1/5 (deterministic partition)
  • Resource limits:
    • max runtime per target
    • max concurrent targets
    • max memory hints (bounded buffers, streaming writes)
  • Retry policy (small, controlled) for transient network failures
  • Graceful cancellation (CTRL+C produces partial outputs safely)

Exit criteria: large scans finish reliably and you can parallelize runs across machines.

Phase 8 — “Finish” (closure, so future-you can maintain it)

  • Document every check ID (docs/checks.md)
  • Golden tests for normalizers (semgrep/osv/gitleaks parsing)
  • GitHub Actions:
    • lint + tests
    • build releases + checksums
  • examples/:
    • sample repo scan output
    • sample URL scan output
    • sample SARIF + HTML plot
  • SECURITY.md + scope/authorization notes

Exit criteria: you can reinstall on a new machine and be productive in <10 minutes.

Optional extensions (only after Phase 6+ is solid)

  • Plugin system (custom checks without forking)
  • Custom JS/TS rules pack (Semgrep rules tailored to your stacks: Next.js/Supabase/etc.)
  • Prometheus exporter during scans
  • “Policy mode” (fail build if severity >= X)
  • Minimal TUI summary (no heavy UI, just a better terminal view)

Phase 9 — Distribution & packaging

  • Homebrew tap + formula (auto-update on release tags)
  • NPM wrapper package (npx tien) that fetches the right binary
  • Release notes automation (Release Drafter or similar)
  • Single checksums.txt per release (all artifacts)
  • SBOM generation (CycloneDX) for release artifacts
  • Artifact signing + provenance (cosign/SLSA)

Exit criteria: installs are one command on macOS/Linux and releases include checksums + SBOM.

Phase 10 — CI/CD integrations & workflow

  • GitHub Action for tien scan (URL/repo) with SARIF upload
  • GitLab CI template snippet
  • Pre-commit hook example for repo scans
  • Baseline/ignore file to suppress known findings
  • Config profiles for local vs ci (or a --profile flag)

Exit criteria: you can drop Tien into a CI pipeline in minutes with clean, actionable output.

Phase 11 — AI-agent security workflow

  • Document a vendor-neutral agent contract for shell-capable coding agents
  • Provide deterministic JSONL/JSON findings for agent reasoning
  • Document the baseline → fix → test → rescan → diff loop
  • Keep exact-host URL authorization and explicit scope mandatory in agent guidance
  • Add a versioned machine-readable MCP output schema
  • Add a local stdio MCP server with typed tools
  • Restrict MCP file access to an operator-selected repository root
  • Expose URL scanning while failing closed unless the operator policy fields loaded at startup authorize every target
  • Remove fixed MCP target and finding ceilings while preserving operator resource budgets
  • Provide a vendor-neutral MCP client configuration template
  • Stream complete MCP scan artifacts with cursor pagination and backpressure, without truncating or reducing scan coverage
  • Add configurable per-host concurrency in addition to the global concurrency budget
  • Define origin-bound signed capability grants for each future named URL plugin or active operation; never reuse the passive built-in url-scan scope
  • Provide maintained client-specific templates for major coding agents
  • Add an optional guided command for non-technical first-time users

Exit criteria: a coding agent can run Tien inside an authorized repository, explain verified evidence, propose a focused fix, and prove the delta without uploading source code or silently expanding scope.

Active testing and public URL plugins are not current capabilities. Any future active operation or named plugin must remain disabled until its dedicated signed capability, consent model, and execution isolation are implemented and reviewed.