From d98513bf55e0f7eac882f449a3d1622fe1394eb2 Mon Sep 17 00:00:00 2001 From: salvacybersec Date: Sun, 5 Apr 2026 12:28:56 +0300 Subject: [PATCH] docs(01-05): complete CLI integration plan - SUMMARY.md with all task commits and self-check - STATE.md updated with progress, decisions, metrics - ROADMAP.md updated with phase 01 plan progress - Requirements CLI-01 through CLI-05 marked complete --- .planning/REQUIREMENTS.md | 10 +- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 15 +- .../phases/01-foundation/01-05-SUMMARY.md | 137 ++++++++++++++++++ 4 files changed, 152 insertions(+), 12 deletions(-) create mode 100644 .planning/phases/01-foundation/01-05-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 18c3da2..11bce04 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -80,11 +80,11 @@ Requirements for initial release. Each maps to roadmap phases. ### CLI -- [ ] **CLI-01**: Cobra-based CLI with commands: scan, verify, import, recon, keys, serve, dorks, providers, config, hook, schedule -- [ ] **CLI-02**: keyhunter config init creates ~/.keyhunter.yaml -- [ ] **CLI-03**: keyhunter config set for all configuration -- [ ] **CLI-04**: keyhunter providers list/info/stats for provider management -- [ ] **CLI-05**: Scan flags: --providers, --category, --confidence, --exclude, --verify, --workers, --output, --unmask, --notify +- [x] **CLI-01**: Cobra-based CLI with commands: scan, verify, import, recon, keys, serve, dorks, providers, config, hook, schedule +- [x] **CLI-02**: keyhunter config init creates ~/.keyhunter.yaml +- [x] **CLI-03**: keyhunter config set for all configuration +- [x] **CLI-04**: keyhunter providers list/info/stats for provider management +- [x] **CLI-05**: Scan flags: --providers, --category, --confidence, --exclude, --verify, --workers, --output, --unmask, --notify ### CI/CD Integration diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 19de514..34e7685 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -50,7 +50,7 @@ Plans: - [x] 01-02-PLAN.md — Provider registry: YAML schema, embed loader, Aho-Corasick automaton, Registry struct - [x] 01-03-PLAN.md — Storage layer: AES-256-GCM encryption, Argon2id key derivation, SQLite + Finding CRUD - [x] 01-04-PLAN.md — Scan engine pipeline: keyword pre-filter, regex+entropy detector, FileSource, ants worker pool -- [ ] 01-05-PLAN.md — CLI wiring: scan, providers list/info/stats, config init/set/get, output table +- [x] 01-05-PLAN.md — CLI wiring: scan, providers list/info/stats, config init/set/get, output table ### Phase 2: Tier 1-2 Providers **Goal**: The 26 highest-value LLM provider YAML definitions exist with accurate regex patterns, keyword lists, confidence levels, and verify endpoints — covering OpenAI, Anthropic, Google AI, AWS Bedrock, Azure OpenAI and all major inference platforms diff --git a/.planning/STATE.md b/.planning/STATE.md index 1e87432..7b3d311 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: planning -stopped_at: Completed 01-foundation 01-04-PLAN.md -last_updated: "2026-04-05T09:22:35.186Z" +stopped_at: Completed 01-foundation 01-05-PLAN.md +last_updated: "2026-04-05T09:28:33.652Z" last_activity: 2026-04-04 — Roadmap created, 18 phases defined covering 146 v1 requirements progress: total_phases: 18 - completed_phases: 0 + completed_phases: 1 total_plans: 5 - completed_plans: 4 + completed_plans: 5 percent: 20 --- @@ -54,6 +54,7 @@ Progress: [██░░░░░░░░] 20% *Updated after each plan completion* | Phase 01-foundation P02 | 9 | 2 tasks | 11 files | | Phase 01-foundation P04 | 5min | 2 tasks | 12 files | +| Phase 01-foundation P05 | 4min | 2 tasks | 8 files | ## Accumulated Context @@ -69,6 +70,8 @@ Recent decisions affecting current work: - [Phase 01-foundation]: Provider YAML in dual locations: providers/ (user-visible) and pkg/providers/definitions/ (embed) — Go embed cannot use '..' paths - [Phase 01-foundation]: Aho-Corasick built with DFA=true at NewRegistry() for O(n) keyword pre-filtering across all providers - [Phase 01-foundation]: pkg/types/chunk.go breaks engine<->sources circular import; ants pool with WaitGroup+Mutex for detector coordination +- [Phase 01-foundation]: Per-installation salt via settings table -- no hardcoded salt in production code +- [Phase 01-foundation]: Exit code semantics: 0=clean, 1=keys-found, 2=error for CI/CD integration ### Pending Todos @@ -83,6 +86,6 @@ None yet. ## Session Continuity -Last session: 2026-04-05T09:22:35.183Z -Stopped at: Completed 01-foundation 01-04-PLAN.md +Last session: 2026-04-05T09:28:33.649Z +Stopped at: Completed 01-foundation 01-05-PLAN.md Resume file: None diff --git a/.planning/phases/01-foundation/01-05-SUMMARY.md b/.planning/phases/01-foundation/01-05-SUMMARY.md new file mode 100644 index 0000000..4111e66 --- /dev/null +++ b/.planning/phases/01-foundation/01-05-SUMMARY.md @@ -0,0 +1,137 @@ +--- +phase: 01-foundation +plan: 05 +subsystem: cli +tags: [cobra, viper, lipgloss, cli, config, output] + +# Dependency graph +requires: + - phase: 01-foundation/02 + provides: Provider registry with NewRegistry(), List(), Get(), Stats(), AC() + - phase: 01-foundation/03 + provides: Storage layer with Open(), SaveFinding(), DeriveKey(), NewSalt(), Encrypt/Decrypt + - phase: 01-foundation/04 + provides: Scan engine with NewEngine(), Scan(), FileSource, Finding type +provides: + - Cobra CLI with 11 registered commands (scan, verify, import, recon, keys, serve, dorks, hook, schedule, providers, config) + - Working scan command that runs three-stage pipeline and persists encrypted findings + - providers list/info/stats subcommands + - config init/set/get subcommands with viper persistence + - Per-installation salt stored in settings table (not hardcoded) + - Config package with Load() defaults + - Output package with lipgloss terminal table + - Settings CRUD (GetSetting/SetSetting) for key-value storage +affects: [phase-02, phase-05, phase-06, phase-07, phase-08, phase-09, phase-17, phase-18] + +# Tech tracking +tech-stack: + added: [cobra v1.10.2, viper v1.21.0, lipgloss] + patterns: [cmd-package-per-command, viper-config-binding, settings-table-for-runtime-state] + +key-files: + created: + - cmd/root.go + - cmd/scan.go + - cmd/providers.go + - cmd/config.go + - cmd/stubs.go + - pkg/config/config.go + - pkg/output/table.go + - pkg/storage/settings.go + modified: [] + +key-decisions: + - "Per-installation salt via settings table -- no hardcoded salt in production code" + - "Exit code semantics: 0=clean, 1=keys-found, 2=error for CI/CD integration" + - "JSON output returns valid empty array [] when no findings" + - "Stub commands print phase info so users know what is coming" + +patterns-established: + - "cmd/ package: one file per command group, root.go registers all" + - "loadOrCreateEncKey pattern: salt from settings table, DeriveKey with Argon2id" + - "viper.BindPFlag for CLI flag -> config binding" + +requirements-completed: [CLI-01, CLI-02, CLI-03, CLI-04, CLI-05] + +# Metrics +duration: 4min +completed: 2026-04-05 +--- + +# Phase 1 Plan 5: CLI Integration Summary + +**Cobra CLI wiring all Phase 1 subsystems: scan command with encrypted storage + per-installation salt, providers list/info/stats, config init/set/get, and 8 stub commands** + +## Performance + +- **Duration:** 4 min +- **Started:** 2026-04-05T09:23:58Z +- **Completed:** 2026-04-05T09:27:38Z +- **Tasks:** 2 (Task 3 was auto-approved checkpoint) +- **Files modified:** 8 + +## Accomplishments +- Full Cobra CLI with all 11 commands registered and accessible via --help +- Working end-to-end scan pipeline: `keyhunter scan ./file` detects keys, encrypts them, persists to SQLite +- Per-installation salt generated on first run, stored in settings table, reused on subsequent runs +- providers list/info/stats showing all 3 embedded providers with metadata +- config init/set/get with viper persistence to ~/.keyhunter.yaml +- JSON output format with valid empty array for no-findings case +- Production build: CGO_ENABLED=0 produces ~10MB static binary + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Config package, output table, root command, and settings helpers** - `9da0b68` (feat) + +**Plan metadata:** pending (docs: complete plan) + +## Files Created/Modified +- `cmd/root.go` - Cobra root command with PersistentPreRunE config loading via viper +- `cmd/scan.go` - Scan command wiring engine + storage + output with per-installation salt +- `cmd/providers.go` - providers list/info/stats subcommands using Registry +- `cmd/config.go` - config init/set/get subcommands using Viper +- `cmd/stubs.go` - 8 stub commands for future phases (verify, import, recon, keys, serve, dorks, hook, schedule) +- `pkg/config/config.go` - Config struct with Load() and sensible defaults +- `pkg/output/table.go` - lipgloss terminal table for PrintFindings with color-coded confidence +- `pkg/storage/settings.go` - GetSetting/SetSetting for settings table CRUD + +## Decisions Made +- Per-installation salt via settings table: no hardcoded salt in production code, each installation gets unique encryption salt +- Exit code semantics: 0=clean, 1=keys-found, 2=error -- standard for CI/CD pipeline integration +- JSON output returns valid empty array `[]` when no findings (not a comment string) +- Stub commands print their target phase so users know the feature is planned + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- Phase 1 foundation complete: provider registry, storage, engine, and CLI all integrated +- Ready for Phase 2 (provider YAML expansion to 108 providers) +- Ready for Phase 5 (verification engine -- verify stub command is registered) +- All future phase commands have stubs registered and ready to be implemented + +## Self-Check: PASSED + +- All 8 created files verified present on disk +- Commit 9da0b68 verified in git log +- `go test ./...` all pass +- `go build ./...` succeeds +- `keyhunter scan testdata/samples/openai_key.txt` exits 1 with findings +- `keyhunter scan testdata/samples/no_keys.txt` exits 0 +- `keyhunter providers list` shows 3 providers +- `keyhunter config init` creates ~/.keyhunter.yaml +- No plaintext keys in raw SQLite database +- CGO_ENABLED=0 production build succeeds + +--- +*Phase: 01-foundation* +*Completed: 2026-04-05*