docs(08-06): complete dorks CLI command tree plan
This commit is contained in:
salvacybersec
126
.planning/phases/08-dork-engine/08-06-SUMMARY.md
Normal file
126
.planning/phases/08-dork-engine/08-06-SUMMARY.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
phase: 08-dork-engine
|
||||
plan: 06
|
||||
subsystem: cli
|
||||
tags: [cobra, dorks, cli, sqlite, github, viper]
|
||||
|
||||
requires:
|
||||
- phase: 08-dork-engine
|
||||
provides: "Registry, Runner, GitHubExecutor, custom_dorks storage"
|
||||
provides:
|
||||
- "keyhunter dorks list/info/export/run/add/delete command tree"
|
||||
- "Injectable newGitHubExecutor seam for cmd tests"
|
||||
- "GITHUB_TOKEN env var bound to viper.dorks.github.token"
|
||||
affects: [phase-09-osint, phase-10-shodan, phase-17-scheduler]
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Package-level executor factory var as test injection seam"
|
||||
- "Embedded+custom dork merge via internal dorkRow helper"
|
||||
- "text/tabwriter for CLI table output (no lipgloss yet for dorks)"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- cmd/dorks.go
|
||||
- cmd/dorks_test.go
|
||||
modified:
|
||||
- cmd/stubs.go
|
||||
|
||||
key-decisions:
|
||||
- "Flag reuse: dorks list and dorks run share dorksFilterSource/Category vars since they never run concurrently — simplifies test reset"
|
||||
- "initDorksDB skips encryption key derivation: dorks CLI only touches plaintext custom_dorks, not the encrypted findings table"
|
||||
- "dorks run wraps ErrSourceNotImplemented with friendly 'coming Phase 9-16' message instead of bare error"
|
||||
- "newGitHubExecutor exposed as package var (not method) so tests can swap without touching dorksRunCmd internals"
|
||||
|
||||
patterns-established:
|
||||
- "Injectable executor factory: var newFooExecutor = func() Executor { ... } for mocking in cmd tests"
|
||||
- "resetDorksFlags helper called from setupDorksTest + between sequential rootCmd.Execute() calls"
|
||||
|
||||
requirements-completed: [DORK-03, DORK-04]
|
||||
|
||||
duration: ~35min
|
||||
completed: 2026-04-05
|
||||
---
|
||||
|
||||
# Phase 8 Plan 06: Dorks CLI Command Tree Summary
|
||||
|
||||
**Full Cobra command tree (list/info/export/run/add/delete) replacing the Phase-8 stub, wiring Registry + custom_dorks + GitHubExecutor through an injectable factory seam for testability.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~35 min
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 3 (1 created in commit 1, 1 created in commit 2, 1 edited)
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Replaced cmd/stubs.go dorks stub with a six-verb subcommand tree
|
||||
- Merged embedded Registry dorks with user-authored custom_dorks in list + export (custom rows prefixed with `*`)
|
||||
- Added --source/--category filtering to both list and run
|
||||
- Wired dorks run to dorks.Runner with GitHub live execution, friendly ErrSourceNotImplemented messaging for other sources, and an ErrMissingAuth hint that points users at GITHUB_TOKEN
|
||||
- Added validation to dorks add: source must be in dorks.ValidSources, category in dorks.ValidCategories, dork id must not collide with an embedded id
|
||||
- Delete refuses embedded ids with a clear error
|
||||
- Bound GITHUB_TOKEN -> dorks.github.token via viper.BindEnv in the dorks init()
|
||||
- 11 end-to-end cmd tests covering every branch, passing against an in-memory SQLite temp DB
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: list/info/export + stub removal** - `b7934ce` (feat)
|
||||
2. **Task 2: run/add/delete + tests** - `c281c96` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `cmd/dorks.go` - Full dorks Cobra command tree, flag declarations, initDorksDB helper, newGitHubExecutor injection seam, init() wiring
|
||||
- `cmd/dorks_test.go` - 11 tests: list filtering, add persistence + marker, invalid source rejection, embedded id collision, embedded delete refusal, custom delete, shodan not-implemented, github missing-token hint, fake-executor run path, yaml export merge, info for both origins
|
||||
- `cmd/stubs.go` - Removed dorksCmd stub declaration (kept notImplemented helper and other stubs)
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Skip encryption in initDorksDB**: The dorks CLI only reads/writes `custom_dorks`, which stores plaintext metadata. Forcing users through the encryption-key derivation path that `openDBWithKey` uses would add a passphrase prompt for commands that don't need it. initDorksDB deliberately calls `storage.Open` directly.
|
||||
- **tabwriter over lipgloss**: Phase 8 plan lists lipgloss as a "nice to have" for the dorks table; the current pkg/output table helpers are keyed to findings, not dorks. Used stdlib text/tabwriter to keep Phase 8 self-contained. A future refactor can swap to lipgloss alongside a shared Table type.
|
||||
- **Package-level executor factory var**: `var newGitHubExecutor = func() dorks.Executor { ... }`. Tests swap it; production code reads it. Avoids forcing the Runner to accept a factory injection or the cmd struct to carry a builder field.
|
||||
- **Shared filter flag vars between list and run**: `dorksFilterSource`/`dorksFilterCategory` are reused across subcommands. Cobra runs one subcommand per invocation, so sharing is safe; `resetDorksFlags` in the test helper guarantees clean state.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None significant. Minor adjustments made inline during implementation:
|
||||
|
||||
1. **[Inline adjustment] renderDork signature switched to `io.Writer`** after initial draft used a structural interface. Single-line fix before the first build.
|
||||
2. **[Inline adjustment] sort key used `rows[i].Dork.Source`** not `rows[i].Source` — dorkRow wraps Dork rather than embedding it, so the field path goes through `.Dork`. Caught by `go build` on the first run and fixed immediately.
|
||||
|
||||
Both were typo-class fixes inside Task 1, pre-commit. Neither required new infrastructure or plan changes.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None. All 11 tests passed on first run after the two trivial compile fixes above; no retries, no flakes.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
Files verified to exist:
|
||||
- `cmd/dorks.go` — FOUND
|
||||
- `cmd/dorks_test.go` — FOUND
|
||||
|
||||
Commits verified in `git log`:
|
||||
- `b7934ce` feat(08-06): add dorks list/info/export commands — FOUND
|
||||
- `c281c96` feat(08-06): add dorks run/add/delete with injectable executor — FOUND
|
||||
|
||||
Build + tests:
|
||||
- `go build ./...` — PASS
|
||||
- `go test ./cmd/... ./pkg/dorks/... ./pkg/storage/...` — PASS
|
||||
- `go test ./...` — PASS (entire workspace green)
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None for tests. For live `keyhunter dorks run --source=github ...`, users must export `GITHUB_TOKEN` with `public_repo` scope, or run `keyhunter config set dorks.github.token <pat>`.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- DORK-03 and DORK-04 requirements satisfied
|
||||
- Plan 08-07 (guardrail/E2E tests) unblocked — the CLI surface it exercises now exists
|
||||
- Phase 9-16 OSINT sources can plug into the dispatcher by registering executors with `dorks.Runner`; the friendly "coming Phase 9-16" message transparently disappears as each one lands
|
||||
|
||||
---
|
||||
*Phase: 08-dork-engine*
|
||||
*Plan: 06*
|
||||
*Completed: 2026-04-05*
|
||||
Reference in New Issue
Block a user