Understand how Banshee works, configure every engine, and run high-signal recon at scale.

What it does

• Generates focused dorks from prompts, research, random modes, and SMART follow-ups.
• Queries Google CSE and Brave Search in parallel with dedupe and pacing.
• Enriches results with tech detection, Wayback intelligence, and monitoring cycles.
• Optionally analyzes documents, HTTP responses, and inline code via gemini-cli.

How it works (in code)

• Run() loads config, initializes caches, and wires a Config pipeline.
• Targets flow from stdin into the dork pipeline; queries are built from flags and AI modules.
• Search helpers fetch results, then dedupe, filter, and enrich them in worker pools.
• Analysis modules summarize findings and persist intelligence in ~/.config/banshee.

Findings it can surface

• Exposed admin panels, dashboards, debug endpoints, and misconfigured services.
• Credentials, tokens, API keys, and secrets in responses or public documents.
• Leaked configs, backups, and sensitive files (PDF, DOCX, XLSX, etc.).
• Legacy or forgotten endpoints via Wayback and CVE-mapped exposures.
• Paste-site leaks tied to your keywords or organization.

Operational boundaries

• Banshee is a discovery and analysis tool, not an exploitation framework.
• Always validate findings manually and respect legal scope.
• Use oos.txt and exclusion flags to stay in-scope.
• Need support? Email gorkem@cyberpars.com.

Exposure discovery

Find admin panels, dashboards, and exposed controls across a target's web surface.

• Start with a focused dork and expand with SMART follow ups.
• Combine with tech detection to prioritize vulnerable stacks.

echo example.com | banshee -q "inurl:admin intitle:login" -a --tech-detect --smart

Sensitive document hunting

Identify public PDFs and office documents, then analyze for secrets or PII.

• Use extensions to focus results and reduce noise.
• Filter to only sensitive documents after analysis.

echo example.com | banshee -e pdf,docx,xlsx --analyze-docs --filter-docs --learn

API and endpoint recon

Find exposed APIs, test endpoints, and config leaks with response analysis.

• Pair with --dedupe to avoid repeated analysis.
• Use targeted dorks like inurl:api or filetype:json.

echo example.com | banshee -q "inurl:api intext:token" --dedupe --analyze-responses

Asset inventory and subdomain expansion

Enumerate subdomains and build an asset inventory.

• Enable deep mode for recursive discovery.
• Use learn mode to persist and reuse discovered assets.
• Works with TLD input for broad mapping (for example, .gov).

echo example.com | banshee -s --deep --learn

Tenant apex expansion

Resolve Microsoft tenant domains and pivot into apex targets tied to a single hostname.

• Uses the OpenID configuration to extract the tenant ID.
• Expands stdin targets before AI and targeted dorking.

echo login.example.com | banshee --find-apex -ai "find admin portals" --smart

Tech and CVE mapping

Update the CVE database and generate specialized dorks per CVE.

• Scope updates with --cve-year and --severity.
• Add --nvd-api-key to speed up CVE updates.

banshee --update-cve-db --cve-year 2025 --severity critical --ai-dork-generation

Cloud asset enumeration

Hunt for exposed cloud storage buckets and asset endpoints tied to your target.

• Random cloud focus generates provider-specific dorks.
• Useful for S3, Azure Blob, GCP Storage, and similar services.

echo example.com | banshee -random cloud -quantity 15 -v

Research mode deep dive

Use AI to research target context and generate higher-signal dorks.

• Increase depth when you need broader coverage.
• Combine with --multi-lang for international targets.

echo example.com | banshee --research --research-depth 3 --multi-lang --learn

Historical attack surface

Mine Wayback history for hidden paths, old assets, and forgotten endpoints.

• Filter by status codes with --wmc.
• Use --smart to follow discovered patterns.

echo example.com | banshee --foresee --wmc 200,301,302 --smart

Continuous monitoring

Run repeated scans with diffing, filtering, and optional analysis per cycle.

• Use --monitor-time to set the cycle interval (minutes).
• Enable --filter-mon to avoid repeating URLs across cycles.

cat domains.txt | banshee --monitor "exposed credentials" --monitor-time 60 --filter-mon --analyze-mon

Leak detection

Scan paste sites for exposed credentials and sensitive strings.

• Provide keywords to focus on specific brands or products.
• Use AI modes for deeper classification and summarization.

echo example.com | banshee --check-leaks --keywords "company api key"

First pass workflow

1. Start narrow with a low page count to validate signal.
2. Expand with AI or SMART once the baseline looks good.
3. Turn on learn mode to persist findings for the next run.

echo example.com | banshee -q "inurl:admin" --pages 5 --adaptive
echo example.com | banshee -ai "admin panels, dashboards, internal tools" --smart --learn

Scope control

• Define exclusions in ~/.config/banshee/oos.txt (wildcards supported).
• Use -x or --exclusions for quick skip lists or files.
• Add --include-dates when you only want recent results.

Performance and quotas

• Limit engines with -engine google or -engine brave when keys are scarce.
• Scale with --workers and control pacing with --delay.
• Keep delay=0 when using --adaptive so the scheduler can adjust.

AI cost control

• Use --dedupe before response analysis to avoid repeated AI calls.
• Use --filter-docs to keep only sensitive documents after analysis.
• Stable prompts improve cache hits in ~/.config/banshee/.ai_cache.json (24 hour TTL).

Random mode hygiene

• Random mode writes used dorks to ~/.config/banshee/.ignore.file.
• Override with --ignore-file or bypass with --flush.
• Use --quantity to bound the number of generated dorks.

Monitor mode runbook

• --monitor builds its own dorks, so do not combine with -q, -ai, or -random.
• --filter-mon dedupes across cycles; --analyze-mon enables per-cycle analysis.
• --monitor is not compatible with --dedupe (use --filter-mon instead).

cat domains.txt | banshee --monitor "api tokens" --monitor-time 45 --filter-mon --analyze-mon

Analysis constraints

• --analyze-responses requires --dedupe.
• --inline-code-analysis cannot be combined with doc or response analysis.
• --analyze-response-only expects URLs from stdin; --analyze-code-only expects code.

Runtime

• Built binary for your OS (Go 1.24.5 is used to build in this repo).
• Network access to Google CSE, Brave Search, and optional NVD API.
• stdin-based input for targets and URL lists.

AI Features

• Node.js + npm installed (required for gemini-cli).
• gemini-cli installed (npm package: @google/generative-ai-cli).
• Gemini API key (or OAuth auth) for AI generation and analysis.
• Optional model override with --model.

Document analysis

• Supports PDF, DOCX, XLSX, PPTX, and text formats.
• Uses AI to classify sensitive findings and store results in sensitive-pdfs.txt.
• Use --filter-docs to remove non-sensitive docs from output.

Response analysis

• Collects HTTP responses for discovered URLs.
• Requires --dedupe to avoid duplicates.
• AI summarizes secrets, admin endpoints, and risky patterns.
• Use --analyze-response-only for direct URLs from stdin.

Inline code analysis

• Extracts inline JS and DOM handlers for XSS risk signals.
• Requires AI mode (-ai, -random, --smart, or --learn).
• Cannot be combined with --analyze-docs or --analyze-response-only.

Code-only analysis

• Pipe code directly to Banshee for AI review.
• Use --analyze-code-only to bypass dorking.

cat script.js | banshee --analyze-code-only --model gemini-2.0-flash-exp

Monitor mode

Provide an intent string and Banshee will continuously run dorks on a schedule.

• --monitor "intent" starts the scheduler.
• --monitor-time sets cycle interval (minutes).
• --filter-mon dedupes URLs across cycles.
• --analyze-mon turns on doc + response analysis per cycle.

Monitor examples

cat domains.txt | banshee --monitor "sensitive pdf" --monitor-time 45
cat domains.txt | banshee --monitor "api tokens" --filter-mon --analyze-mon

Monitor mode is compatible with AI, SMART, LEARN, research, and multi-lang flows.

Learn mode

• Stores successful URLs, detected tech, paths, and patterns.
• Improves SMART follow-ups and AI dork generation.
• Use --view-intel to inspect intelligence per target.
• Use --export-intel to save JSON snapshots.

Wayback foresee

• Queries the Wayback Machine for historical URLs.
• Extracts subdomains, parameters, file patterns, and admin paths.
• Controls cache with --no-wayback-cache or --clear-wayback-cache.
• Optional status code filters via --wmc.

Result output

• Without -o, unique URLs are printed to stdout (sorted).
• With -o, Banshee appends only new unique URLs (anew style).
• The output file is created if missing; use -v to log preloaded URLs.
• Ideal for long-running or repeated scans where you want one growing, de-duplicated file.
• --no-colors produces clean output for piping into other tools.
• --export-intel writes a JSON snapshot; --view-intel prints to stdout.

Analysis artifacts

• Document analysis logs sensitive hits to sensitive-pdfs.txt.
• Learn mode stores per-target intelligence and upgrades future scans.
• SMART uses successful.txt patterns to generate focused dorks.

See Internal Files for full paths and formats.

Cache behavior

• AI responses are cached to reduce repeated prompts (default 24 hour TTL).
• Wayback caches reduce API load; TTL is configurable in ~/.config/banshee/.config.
• Clear caches when you need a full refresh of results.