321 lines
15 KiB
Markdown
321 lines
15 KiB
Markdown
---
|
|
phase: 05-verification-engine
|
|
plan: 05
|
|
type: execute
|
|
wave: 2
|
|
depends_on: [05-01, 05-02, 05-03, 05-04]
|
|
files_modified:
|
|
- cmd/scan.go
|
|
- cmd/scan_test.go
|
|
- pkg/output/table.go
|
|
- pkg/output/table_test.go
|
|
autonomous: true
|
|
requirements: [VRFY-01, VRFY-04, VRFY-05]
|
|
must_haves:
|
|
truths:
|
|
- "keyhunter scan --verify triggers EnsureConsent before any verify HTTP calls; declined consent skips verification but still prints findings"
|
|
- "Verified findings have VerifyStatus populated and are persisted via SaveFinding with verify_* columns set"
|
|
- "--verify-timeout=30s changes the per-key HTTP timeout from default 10s"
|
|
- "--verify-workers=N sets the ants pool size for parallel verification"
|
|
- "Output table shows a VERIFY column: ✓ live / ✗ dead / ⚠ rate-limited / ? unknown / ! error"
|
|
- "Verification only runs after scan completes (batch mode) — all findings collected, then verified"
|
|
artifacts:
|
|
- path: "cmd/scan.go"
|
|
provides: "--verify wiring: consent -> verifier -> save -> display"
|
|
contains: "verify.EnsureConsent"
|
|
- path: "pkg/output/table.go"
|
|
provides: "Verification status column"
|
|
contains: "VERIFY"
|
|
key_links:
|
|
- from: "cmd/scan.go"
|
|
to: "pkg/verify.HTTPVerifier.VerifyAll"
|
|
via: "after scan findings collected"
|
|
pattern: "VerifyAll"
|
|
- from: "cmd/scan.go"
|
|
to: "pkg/verify.EnsureConsent"
|
|
via: "gate before verification"
|
|
pattern: "EnsureConsent"
|
|
- from: "cmd/scan.go"
|
|
to: "storage.SaveFinding"
|
|
via: "persists verified findings with VerifyStatus populated"
|
|
pattern: "storeFinding.VerifyStatus"
|
|
---
|
|
|
|
<objective>
|
|
Wire Plans 05-02/03/04 together into the scan command. Add `--verify-timeout` and `--verify-workers` flags, gate verification behind consent, run the verifier over collected findings, persist verify results, and render a new verify column in the output table.
|
|
|
|
Purpose: End-user visible feature — this is where VRFY-01 (prompt), VRFY-04 (metadata display), and VRFY-05 (configurable timeout) come together.
|
|
Output: Working `keyhunter scan --verify` command that prompts on first use and displays verification status.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/phases/05-verification-engine/05-CONTEXT.md
|
|
@cmd/scan.go
|
|
@pkg/output/table.go
|
|
@pkg/engine/finding.go
|
|
|
|
<interfaces>
|
|
Available after Wave 1 completes:
|
|
|
|
```go
|
|
// pkg/verify/consent.go (Plan 05-02)
|
|
func EnsureConsent(db *storage.DB, in io.Reader, out io.Writer) (bool, error)
|
|
|
|
// pkg/verify/verifier.go (Plan 05-03)
|
|
func NewHTTPVerifier(timeout time.Duration) *HTTPVerifier
|
|
func (v *HTTPVerifier) VerifyAll(ctx, []engine.Finding, *providers.Registry, workers int) <-chan Result
|
|
|
|
// pkg/verify/result.go
|
|
type Result struct {
|
|
ProviderName string
|
|
KeyMasked string
|
|
Status string // StatusLive/Dead/RateLimited/Error/Unknown
|
|
HTTPCode int
|
|
Metadata map[string]string
|
|
RetryAfter time.Duration
|
|
ResponseTime time.Duration
|
|
Error string
|
|
}
|
|
|
|
// pkg/storage/findings.go (Plan 05-01)
|
|
type Finding struct {
|
|
// ... existing ...
|
|
Verified bool
|
|
VerifyStatus string
|
|
VerifyHTTPCode int
|
|
VerifyMetadata map[string]string
|
|
}
|
|
```
|
|
|
|
Current scan command already has `flagVerify bool`. This plan extends with `flagVerifyTimeout time.Duration` and `flagVerifyWorkers int`.
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 1: Wire verifier into cmd/scan.go with consent and flags</name>
|
|
<files>cmd/scan.go, cmd/scan_test.go</files>
|
|
<behavior>
|
|
- New flags registered: `--verify-timeout` (default 10s), `--verify-workers` (default 10)
|
|
- When --verify is set: collect all findings, call EnsureConsent(db, os.Stdin, os.Stderr)
|
|
- If consent declined: print notice to stderr, skip verification, still display + persist unverified findings
|
|
- If consent granted: run NewHTTPVerifier(timeout).VerifyAll(ctx, findings, reg, workers), read results from channel, match back to findings by (provider+KeyMasked), update Finding.Verified/VerifyStatus/VerifyHTTPCode/VerifyMetadata
|
|
- SaveFinding is called AFTER verification so verify_* columns are persisted in the same row (refactor current loop: collect first, verify second, save third)
|
|
- On scan errors or no findings: verification path is a no-op
|
|
</behavior>
|
|
<action>
|
|
1. In `cmd/scan.go`:
|
|
|
|
a. Add imports: `"io"` (may already exist), `"github.com/salvacybersec/keyhunter/pkg/verify"`, `"time"` (already there).
|
|
|
|
b. Add new package-level flag variables near existing flagVerify:
|
|
```go
|
|
var (
|
|
flagVerifyTimeout time.Duration
|
|
flagVerifyWorkers int
|
|
)
|
|
```
|
|
|
|
c. In the `init()` function add:
|
|
```go
|
|
scanCmd.Flags().DurationVar(&flagVerifyTimeout, "verify-timeout", 10*time.Second, "per-key verification HTTP timeout (default 10s)")
|
|
scanCmd.Flags().IntVar(&flagVerifyWorkers, "verify-workers", 10, "parallel workers for key verification (default 10)")
|
|
```
|
|
|
|
d. Refactor the scan loop in `RunE`. Currently the loop saves each finding as it comes from the channel. Change to:
|
|
```go
|
|
// Collect findings first (no immediate save) so verification can populate
|
|
// verify_* fields before persistence.
|
|
var findings []engine.Finding
|
|
for f := range ch {
|
|
findings = append(findings, f)
|
|
}
|
|
```
|
|
|
|
e. After the collection loop, add the verification block:
|
|
```go
|
|
if flagVerify && len(findings) > 0 {
|
|
granted, err := verify.EnsureConsent(db, os.Stdin, os.Stderr)
|
|
if err != nil {
|
|
return fmt.Errorf("consent check: %w", err)
|
|
}
|
|
if !granted {
|
|
fmt.Fprintln(os.Stderr, "Verification skipped (consent not granted). Run `keyhunter legal` for details.")
|
|
} else {
|
|
verifier := verify.NewHTTPVerifier(flagVerifyTimeout)
|
|
resultsCh := verifier.VerifyAll(context.Background(), findings, reg, flagVerifyWorkers)
|
|
// Build an index for back-assignment
|
|
idx := make(map[string]int, len(findings))
|
|
for i, f := range findings {
|
|
key := f.ProviderName + "|" + f.KeyMasked
|
|
idx[key] = i
|
|
}
|
|
for r := range resultsCh {
|
|
if i, ok := idx[r.ProviderName+"|"+r.KeyMasked]; ok {
|
|
findings[i].Verified = true
|
|
findings[i].VerifyStatus = r.Status
|
|
findings[i].VerifyHTTPCode = r.HTTPCode
|
|
findings[i].VerifyMetadata = r.Metadata
|
|
if r.Error != "" {
|
|
findings[i].VerifyError = r.Error
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
f. Then persist all findings (moved out of collection loop) with verify fields now populated:
|
|
```go
|
|
for _, f := range findings {
|
|
storeFinding := storage.Finding{
|
|
ProviderName: f.ProviderName,
|
|
KeyValue: f.KeyValue,
|
|
KeyMasked: f.KeyMasked,
|
|
Confidence: f.Confidence,
|
|
SourcePath: f.Source,
|
|
SourceType: f.SourceType,
|
|
LineNumber: f.LineNumber,
|
|
Verified: f.Verified,
|
|
VerifyStatus: f.VerifyStatus,
|
|
VerifyHTTPCode: f.VerifyHTTPCode,
|
|
VerifyMetadata: f.VerifyMetadata,
|
|
}
|
|
if _, err := db.SaveFinding(storeFinding, encKey); err != nil {
|
|
fmt.Fprintf(os.Stderr, "warning: failed to save finding: %v\n", err)
|
|
}
|
|
}
|
|
```
|
|
|
|
g. Leave the output rendering call unchanged (Task 2 handles the display column).
|
|
|
|
2. Create `cmd/scan_test.go` (or append if present) with:
|
|
- `TestScan_VerifyFlag_DeclinedConsent_SkipsVerification` — set up a scan command with --verify, provide stdin reader "no\n", run against a test file with one fake key, assert that the resulting in-memory finding has Verified=false and the scan still completes
|
|
- `TestScan_VerifyFlag_GrantedConsent_PopulatesStatus` — pre-seed settings "verify.consent" = "granted", run scan --verify against a file containing a test pattern, assert at least one finding has Verified=true after the run
|
|
|
|
These tests will likely need to refactor scanCmd to accept injected stdin and a test helper to invoke the command function directly (not via cobra execution). If that's too invasive, scope Task 1 tests to:
|
|
- `TestScan_VerifyFlags_Registered` — ensure --verify-timeout and --verify-workers flags exist on scanCmd with correct defaults (call `scanCmd.Flags().Lookup("verify-timeout")` and assert non-nil + default "10s")
|
|
|
|
Prefer the lightweight flag-registration test to avoid pulling the full scan path into tests. Add at least one behavioral integration test if straightforward; otherwise document the limitation in the task-level SUMMARY.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/salva/Documents/apikey && go build ./... && go test ./cmd/... -run VerifyFlag -v</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- `grep -q 'verify.EnsureConsent' cmd/scan.go`
|
|
- `grep -q 'verifier.VerifyAll\|NewHTTPVerifier' cmd/scan.go`
|
|
- `grep -q 'verify-timeout' cmd/scan.go`
|
|
- `grep -q 'verify-workers' cmd/scan.go`
|
|
- `go build ./...` succeeds
|
|
- `go run . scan --help` shows --verify, --verify-timeout, --verify-workers flags
|
|
- scan_test.go flag-registration test passes
|
|
</acceptance_criteria>
|
|
<done>Scan command orchestrates consent → verification → save with configurable timeout and workers.</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 2: Output table shows verification status column and metadata</name>
|
|
<files>pkg/output/table.go, pkg/output/table_test.go</files>
|
|
<behavior>
|
|
- When any finding has Verified=true, PrintFindings renders an extra VERIFY column
|
|
- Symbol mapping: "live"=✓ (green), "dead"=✗ (red), "rate_limited"=⚠ (yellow), "error"=! (red), "unknown"=? (gray), "" (unverified)=empty cell
|
|
- When any finding has VerifyMetadata, a second summary line per finding shows key: value pairs (e.g. " org: Acme Corp, tier: plus")
|
|
- When no findings are verified, table layout is unchanged from Phase 1 (backward compat)
|
|
</behavior>
|
|
<action>
|
|
1. In `pkg/output/table.go`, modify `PrintFindings`:
|
|
|
|
a. Compute `anyVerified := false` by scanning findings once before printing.
|
|
|
|
b. If anyVerified, add a VERIFY column header between KEY and CONFIDENCE (or after LINE — pick after LINE for minimal disruption to column widths):
|
|
```go
|
|
fmt.Fprintf(os.Stdout, "%-20s %-40s %-10s %-30s %-5s %s\n",
|
|
styleHeader.Render("PROVIDER"),
|
|
styleHeader.Render("KEY"),
|
|
styleHeader.Render("CONFIDENCE"),
|
|
styleHeader.Render("SOURCE"),
|
|
styleHeader.Render("LINE"),
|
|
styleHeader.Render("VERIFY"),
|
|
)
|
|
```
|
|
|
|
c. Add helper:
|
|
```go
|
|
func verifySymbol(f engine.Finding) string {
|
|
if !f.Verified {
|
|
return ""
|
|
}
|
|
switch f.VerifyStatus {
|
|
case "live":
|
|
return lipgloss.NewStyle().Foreground(lipgloss.Color("2")).Render("✓ live")
|
|
case "dead":
|
|
return lipgloss.NewStyle().Foreground(lipgloss.Color("1")).Render("✗ dead")
|
|
case "rate_limited":
|
|
return lipgloss.NewStyle().Foreground(lipgloss.Color("3")).Render("⚠ rate")
|
|
case "error":
|
|
return lipgloss.NewStyle().Foreground(lipgloss.Color("1")).Render("! err")
|
|
default:
|
|
return lipgloss.NewStyle().Foreground(lipgloss.Color("8")).Render("? unk")
|
|
}
|
|
}
|
|
```
|
|
|
|
d. In the per-finding loop, when anyVerified, append verifySymbol(f) as the final column. When len(f.VerifyMetadata) > 0, print a second indented line:
|
|
```go
|
|
if len(f.VerifyMetadata) > 0 {
|
|
parts := make([]string, 0, len(f.VerifyMetadata))
|
|
for k, v := range f.VerifyMetadata {
|
|
parts = append(parts, fmt.Sprintf("%s: %s", k, v))
|
|
}
|
|
sort.Strings(parts) // deterministic order
|
|
fmt.Fprintf(os.Stdout, " ↳ %s\n", strings.Join(parts, ", "))
|
|
}
|
|
```
|
|
Add the `sort` and `strings` imports.
|
|
|
|
2. Create `pkg/output/table_test.go`:
|
|
- `TestPrintFindings_NoVerification_Unchanged` — findings with Verified=false, capture stdout via os.Pipe redirect, assert output does not contain "VERIFY" header (backward compat)
|
|
- `TestPrintFindings_LiveVerification_ShowsCheck` — finding with Verified=true, VerifyStatus="live", assert stdout contains "VERIFY" and "live"
|
|
- `TestPrintFindings_Metadata_Rendered` — finding with VerifyMetadata={"org":"Acme","tier":"plus"}, assert stdout contains "org: Acme" and "tier: plus" on the indented metadata line
|
|
|
|
Capture stdout using the `os.Pipe` + `os.Stdout = w` swap pattern, restore after test. Strip ANSI escape sequences before asserting content (lipgloss output contains them). Use a small helper `stripANSI(s string) string` with a regex `\x1b\[[0-9;]*m`.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/salva/Documents/apikey && go test ./pkg/output/... -v</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- `grep -q 'VERIFY' pkg/output/table.go`
|
|
- `grep -q 'verifySymbol\|VerifyStatus' pkg/output/table.go`
|
|
- All 3 table tests pass
|
|
- `go build ./...` succeeds
|
|
- Manual: `go run . scan ./testdata` (without --verify) output is unchanged; with --verify shows VERIFY column
|
|
</acceptance_criteria>
|
|
<done>Output table renders verify column and metadata line when findings are verified; backward compatible when not.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- `go build ./...` clean
|
|
- `go test ./... -v` across all modified packages green
|
|
- `go run . scan --help` shows `--verify`, `--verify-timeout`, `--verify-workers`
|
|
- Manual smoke: create a file with a fake `sk-proj-...` string, run `go run . scan file.txt --verify`, first run prompts for consent, subsequent runs skip prompt
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- VRFY-01: consent prompt gates --verify on first use
|
|
- VRFY-04: metadata displayed under finding when extracted
|
|
- VRFY-05: --verify-timeout and --verify-workers flags work
|
|
- Unverified scans unchanged from Phase 4 behavior
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/05-verification-engine/05-05-SUMMARY.md`
|
|
</output>
|