Home

GitHunter: Building a Version-Control Workflow for Security Research

GitHunter saved tools: a practical deep guide

GitHunter is a local workspace for authorized security research. Its saved tools feature remembers a command, runs it only when you explicitly request it, and can import the resulting assets into the current project. It is useful when the same passive discovery or validation command is used repeatedly.

Use external tools only against targets you are authorized to assess. A scope rule recorded in GitHunter is a record of your decision; it is not permission by itself.

1. Start with a project and clear scope

mkdir authorized-example
cd authorized-example
githunter init --name authorized-example
githunter target add example.com --authorization "Written authorization"
githunter scope add example.com
githunter scope add "*.example.com"
githunter scope out add admin.example.com

Before a tool run, check a value when needed:

githunter scope check api.example.com

Only IN_SCOPE is a positive match. OUT_OF_SCOPE and UNKNOWN should not be treated as approval to test.

2. Save a tool without running it

The simplest form saves a familiar command line. GitHunter parses it itself; it does not pass it to a shell.

githunter tool add "subfinder -d {target} -silent" --name subfinder-passive

At this point nothing has executed. Inspect the definition first:

githunter tool show subfinder-passive
githunter tool explain subfinder-passive
githunter tool validate subfinder-passive

validate checks the definition syntax and whether the executable is on your PATH. Commands containing shell control or redirection operators such as ;, &, >, <, or backticks are rejected. This prevents a saved command from unexpectedly using shell behavior.

3. Use placeholders correctly

{target} is replaced with the selected value at run time:

githunter tool run subfinder-passive --target example.com

For a saved pipeline, GitHunter also recognizes {asset}, {input}, and {scope}. Pipelines use | only; each stage runs as a separate process and the previous stage's stdout becomes the next stage's stdin.

githunter tool add "subfinder -d {target} -silent | dnsx -silent" --name dns-check
githunter tool explain dns-check

Do not add shell redirection such as > results.txt. Let GitHunter import the stdout, or use a separate command you run yourself when a file is required.

4. Choose exactly one input source

Every tool run command resolves one value. If no option is supplied, GitHunter uses the first saved project target.

# Explicit value
githunter tool run subfinder-passive --target example.com

# One saved asset
githunter tool run subfinder-passive --asset api.example.com

# First usable (non-empty, non-comment) line in a file
githunter tool run subfinder-passive --file inputs.txt

# First usable line received through standard input
printf 'api.example.com\n' | githunter tool run subfinder-passive --stdin

# First asset marked with the requested scope state
githunter tool run subfinder-passive --scope in_scope

Do not combine these selectors. For example, --target and --asset together are rejected because the selected input would be ambiguous.

5. Understand output import

Tool stdout is imported into GitHunter assets by default. This works well for tools that output one domain, URL, IP, or other supported asset per line.

githunter tool run subfinder-passive --target example.com
githunter asset list --source subfinder-passive

Use --no-import when you want to execute the tool but do not want its stdout stored as project assets:

githunter tool run subfinder-passive --target example.com --no-import

Keep tool output machine-friendly. If a tool prints banners or verbose logs to stdout, configure its quiet/JSON-lines mode where available, or use --no-import and review the result separately.

6. Timeouts, live status, and errors

Set a positive timeout when a command should not run indefinitely:

githunter tool add "subfinder -d {target} -silent" \
  --name subfinder-passive --timeout 60

In an interactive terminal, GitHunter displays a live elapsed-time indicator. It reports Completed, Failed, or Timed out when the process finishes. Ctrl+C stops a run that you want to cancel. A non-zero exit status is treated as a failed run and its stdout is not imported.

7. Run several saved tools or a workflow

Run every enabled tool with the same selected value:

githunter tool run all --target example.com

For a fixed sequence, create a workflow. Each step must name an existing saved tool.

githunter workflow add --name passive-recon \
  --description "Authorized passive collection" \
  --steps subfinder-passive,dns-check

githunter workflow run passive-recon --target example.com

Workflows stop at the first failed step. Review and validate each tool before placing it in a workflow.

8. Preserve the result

After importing reviewed findings, make a snapshot. A later snapshot can show what changed.

githunter snapshot create --note "Passive baseline"
githunter asset list --scope in_scope

# Run authorized collection again later, then:
githunter snapshot create --note "Follow-up"
githunter diff

Useful review commands:

githunter tool list
githunter timeline
githunter status
githunter recommend

The safest routine is: confirm authorization, save and validate a command, run it explicitly with one selected input, review imported assets, and snapshot the state you want to keep.