259 lines
9.7 KiB
Markdown
259 lines
9.7 KiB
Markdown
---
|
|
phase: 08-dork-engine
|
|
plan: 06
|
|
type: execute
|
|
wave: 3
|
|
depends_on: [08-01, 08-02, 08-03, 08-04, 08-05]
|
|
files_modified:
|
|
- cmd/dorks.go
|
|
- cmd/dorks_test.go
|
|
- cmd/stubs.go
|
|
- cmd/root.go
|
|
autonomous: true
|
|
requirements:
|
|
- DORK-03
|
|
- DORK-04
|
|
must_haves:
|
|
truths:
|
|
- "`keyhunter dorks list` prints a table of embedded + custom dorks"
|
|
- "`keyhunter dorks list --source=github --category=frontier` filters correctly"
|
|
- "`keyhunter dorks info <id>` prints full dork detail"
|
|
- "`keyhunter dorks run --source=github --id=<id>` calls GitHubExecutor"
|
|
- "`keyhunter dorks run --source=shodan` returns ErrSourceNotImplemented with a helpful message"
|
|
- "`keyhunter dorks add --source=github --category=frontier --query=... --description=...` persists to custom_dorks table"
|
|
- "`keyhunter dorks delete <id>` removes from custom_dorks and refuses embedded IDs"
|
|
- "`keyhunter dorks export --format=yaml` dumps embedded+custom"
|
|
artifacts:
|
|
- path: "cmd/dorks.go"
|
|
provides: "dorks Cobra command tree replacing stub"
|
|
contains: "dorksCmd.AddCommand"
|
|
key_links:
|
|
- from: "cmd/dorks.go"
|
|
to: "pkg/dorks.Registry"
|
|
via: "dorks.NewRegistry()"
|
|
pattern: "dorks.NewRegistry"
|
|
- from: "cmd/dorks.go run"
|
|
to: "pkg/dorks.GitHubExecutor"
|
|
via: "NewGitHubExecutor(viper.GetString(\"dorks.github.token\"))"
|
|
pattern: "NewGitHubExecutor"
|
|
- from: "cmd/dorks.go add/delete"
|
|
to: "storage.DB custom_dorks CRUD"
|
|
via: "db.SaveCustomDork / DeleteCustomDork"
|
|
pattern: "SaveCustomDork|DeleteCustomDork"
|
|
---
|
|
|
|
<objective>
|
|
Replace the Phase-8 dorks stub in cmd/stubs.go with a full Cobra command tree:
|
|
list / run / add / export / info / delete. Wires the Registry (embedded dorks)
|
|
together with storage custom_dorks (user dorks) and the GitHubExecutor (live
|
|
execution). Satisfies DORK-03 (all four CLI verbs) and DORK-04 (category
|
|
filtering via --category flag).
|
|
|
|
Purpose: User-facing surface of the dork engine — everything built in 08-01
|
|
through 08-05 becomes usable from the CLI.
|
|
Output: Working `keyhunter dorks ...` subcommands.
|
|
</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/08-dork-engine/08-CONTEXT.md
|
|
@.planning/phases/08-dork-engine/08-01-PLAN.md
|
|
@.planning/phases/08-dork-engine/08-05-PLAN.md
|
|
@cmd/stubs.go
|
|
@cmd/root.go
|
|
@cmd/keys.go
|
|
@pkg/dorks/schema.go
|
|
@pkg/dorks/registry.go
|
|
@pkg/dorks/executor.go
|
|
@pkg/storage/custom_dorks.go
|
|
|
|
<interfaces>
|
|
<!-- From prior plans -->
|
|
```go
|
|
// pkg/dorks
|
|
func NewRegistry() (*Registry, error)
|
|
func (r *Registry) List() []Dork
|
|
func (r *Registry) Get(id string) (Dork, bool)
|
|
func (r *Registry) ListBySource(src string) []Dork
|
|
func (r *Registry) ListByCategory(cat string) []Dork
|
|
func NewGitHubExecutor(token string) *GitHubExecutor
|
|
|
|
// pkg/storage
|
|
func (db *DB) SaveCustomDork(d CustomDork) (int64, error)
|
|
func (db *DB) ListCustomDorks() ([]CustomDork, error)
|
|
func (db *DB) GetCustomDorkByDorkID(dorkID string) (CustomDork, error)
|
|
func (db *DB) DeleteCustomDork(id int64) (int64, error)
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: cmd/dorks.go command tree (list/info/export)</name>
|
|
<files>cmd/dorks.go, cmd/stubs.go, cmd/root.go</files>
|
|
<action>
|
|
1. Remove `var dorksCmd` from cmd/stubs.go (keep the rest of the stubs file
|
|
untouched).
|
|
|
|
2. Create cmd/dorks.go with the full command tree. Wire into root.go by
|
|
leaving the existing `rootCmd.AddCommand(dorksCmd)` in place — only the
|
|
declaration moves.
|
|
|
|
Structure:
|
|
```go
|
|
package cmd
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"os"
|
|
"strings"
|
|
|
|
"github.com/spf13/cobra"
|
|
"github.com/spf13/viper"
|
|
"gopkg.in/yaml.v3"
|
|
|
|
"github.com/<OWNER>/<REPO>/pkg/dorks"
|
|
"github.com/<OWNER>/<REPO>/pkg/storage"
|
|
)
|
|
|
|
var (
|
|
dorksFilterSource string
|
|
dorksFilterCategory string
|
|
dorksRunID string
|
|
dorksRunLimit int
|
|
dorksAddSource string
|
|
dorksAddCategory string
|
|
dorksAddID string
|
|
dorksAddName string
|
|
dorksAddQuery string
|
|
dorksAddDescription string
|
|
dorksExportFormat string
|
|
)
|
|
|
|
var dorksCmd = &cobra.Command{
|
|
Use: "dorks",
|
|
Short: "Manage and run dork queries (DORK-01..DORK-04)",
|
|
}
|
|
|
|
// list, info, run, add, delete, export subcommands declared here.
|
|
```
|
|
|
|
Replace `<OWNER>/<REPO>` by reading the existing `module` line in
|
|
/home/salva/Documents/apikey/go.mod before writing the file (use the same
|
|
import path that cmd/keys.go uses).
|
|
|
|
**dorks list** — merges Registry.List() + db.ListCustomDorks(). Applies
|
|
--source and --category filters in memory. Prints a lipgloss table
|
|
(reuse pkg/output helpers if present, else a simple tab-aligned fmt). Mark
|
|
custom rows with a `*` prefix on the ID column.
|
|
|
|
**dorks info <id>** — looks up by dork_id first in Registry.Get, falls back
|
|
to db.GetCustomDorkByDorkID. Prints all fields including tags.
|
|
|
|
**dorks export [--format=yaml|json]** — emits a single combined list of
|
|
embedded + custom dorks in the requested format. Default yaml.
|
|
|
|
Use `initDorksDB()` helper that opens storage.DB using the same path logic
|
|
cmd/keys.go uses (viper.GetString("database.path")) so tests can inject a
|
|
temp path.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/salva/Documents/apikey && go build ./... && go run ./ dorks list --source=github --category=frontier 2>&1 | grep -Ei '(openai|anthropic)'</automated>
|
|
</verify>
|
|
<done>
|
|
list/info/export commands compile and run. Filtering by source/category
|
|
works. Stub removed from cmd/stubs.go.
|
|
</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 2: dorks run/add/delete + command tests</name>
|
|
<files>cmd/dorks.go, cmd/dorks_test.go</files>
|
|
<behavior>
|
|
- Test: `dorks add` persists a custom dork and `dorks list` shows it marked with `*`
|
|
- Test: `dorks delete <custom-id>` removes it; `dorks delete <embedded-id>` errors "embedded dorks cannot be deleted"
|
|
- Test: `dorks run --source=shodan --id=<shodan-id>` returns error wrapping ErrSourceNotImplemented
|
|
- Test: `dorks run --source=github --id=<id>` with empty GITHUB_TOKEN returns ErrMissingAuth setup message
|
|
- Test: `dorks run --source=github --id=<id>` with injected fake GitHubExecutor returns mocked matches
|
|
- Use cobra.Command.SetArgs + bytes.Buffer to capture stdout in tests; inject
|
|
a tempdir DB path via viper.Set("database.path", tmp).
|
|
</behavior>
|
|
<action>
|
|
1. Add **dorks add** subcommand to cmd/dorks.go. Builds a storage.CustomDork
|
|
from flags, validates source and category against dorks.ValidSources /
|
|
valid categories (frontier, specialized, infrastructure, emerging,
|
|
enterprise), calls db.SaveCustomDork. Fails if dork_id collides with an
|
|
embedded dork ID.
|
|
|
|
2. Add **dorks delete <dork-id>** subcommand. If the ID matches an embedded
|
|
dork, print "embedded dorks cannot be deleted" and exit 2. Otherwise
|
|
call db.GetCustomDorkByDorkID -> db.DeleteCustomDork.
|
|
|
|
3. Add **dorks run** subcommand:
|
|
- Required flags: --source; optional: --id, --category, --limit (default 10)
|
|
- If --id is set, run just that single dork (from registry or custom)
|
|
- Else, run all dorks matching --source and --category filters
|
|
- For each dork: dispatch via a Runner wired only with GitHub executor.
|
|
Non-github sources return fmt.Errorf wrapping ErrSourceNotImplemented
|
|
with message: "source %q not yet implemented (coming Phase 9-16)"
|
|
- Print matches as a simple list: `[dork-id] URL (path) snippet`
|
|
- Exit code 0 on success (even with zero matches), 2 on any executor
|
|
error other than ErrSourceNotImplemented (which should exit 2 also
|
|
but with the friendly message).
|
|
|
|
4. Extract the executor factory into a package-level var so tests can inject:
|
|
```go
|
|
var newGitHubExecutor = func() dorks.Executor {
|
|
return dorks.NewGitHubExecutor(viper.GetString("dorks.github.token"))
|
|
}
|
|
```
|
|
Tests override `newGitHubExecutor` to return a fake Executor.
|
|
|
|
5. Create cmd/dorks_test.go:
|
|
- Helper `setupDorksTest(t)` — creates tempdir, viper.Set("database.path", ...),
|
|
opens DB via initDorksDB, runs schema, returns cleanup func.
|
|
- Tests execute rootCmd with SetArgs([]string{"dorks", "add", "--source=github", ...}).
|
|
- Capture output via rootCmd.SetOut(&buf).
|
|
- FakeExecutor type implements dorks.Executor with a stubbed Execute()
|
|
returning canned Match slice.
|
|
|
|
6. **Config binding:** In cmd/root.go initConfig, ensure
|
|
`viper.BindEnv("dorks.github.token", "GITHUB_TOKEN")` is set so the
|
|
executor picks up the env var.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/salva/Documents/apikey && go test ./cmd/... -run Dorks -v</automated>
|
|
</verify>
|
|
<done>
|
|
run/add/delete subcommands work end-to-end. All cmd/dorks_test.go tests pass.
|
|
GITHUB_TOKEN env var bound. Embedded dork deletion refused.
|
|
</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- `go build ./...` succeeds
|
|
- `go test ./cmd/... ./pkg/dorks/... ./pkg/storage/...` passes
|
|
- `./keyhunter dorks list --source=github --category=frontier` shows real dorks
|
|
- `./keyhunter dorks run --source=shodan --id=shodan-ollama-default` emits ErrSourceNotImplemented message
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- DORK-03 satisfied: list, run, add, export, info, delete all functional
|
|
- DORK-04 satisfied: --source and --category filters applied in both list and run
|
|
- dorks stub removed from cmd/stubs.go
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/08-dork-engine/08-06-SUMMARY.md`
|
|
</output>
|