reconFTW is a tool designed to perform automated recon on a target domain by running the best set of tools to perform scanning and finding out vulnerabilities
Project
reconFTW
reconFTW is a comprehensive bash-based reconnaissance automation framework used by bug bounty hunters, penetration testers, and security researchers. It orchestrates 70+ external security tools (Go, Python, Rust) across subdomain enumeration, web probing, OSINT, and vulnerability scanning, producing structured per-target output trees with optional Axiom distributed execution, AI reporting, monitor/incremental mode, and Slack/Telegram/Discord notifications.
Core Value: Run one command, get a complete recon picture of a target — passive, active, and vulnerability layers — with resumable checkpoints, structured output, and zero-touch tool orchestration.
Constraints
- Tech stack: Bash 4.3+ — Required for
wait -n,mapfile, associative arrays. macOS users must have Homebrew bash; auto re-exec is best-effort. - External tools: 70+ runtime dependencies — Most install via
go install @latest(no version pinning), which is convenient but a known supply-chain risk. - Single process: All modules sourced into one shell — No subshell isolation between modules; all state shared via globals. Workflow functions must save/restore globals they override (see
passive()pattern). - Resume semantics: Checkpoint files are touch-once at
end_func— Interrupted functions re-run from scratch on next invocation; partial outputs are not detected. - Single-operator: Designed for one user per target run — No locking, no multi-user state, no concurrent runs against the same target dir.
- Output stability:
Recon/<domain>/tree is a public contract — Subdirectory names and filenames are consumed by downstream pipelines, scripts, and parsers; renames are breaking changes. - macOS compatibility: GNU coreutils + GNU sed + GNU getopt required — System BSD versions are not supported.
- CI budget: Integration-full is weekly cron — Unit + smoke are per-push; adding heavy integration tests must respect this split.
Technology Stack
Languages
- Bash 4+ - All core framework logic (
reconftw.sh,modules/*.sh,lib/*.sh,install.sh) - Python 3.7+ - Python-backed tools (each runs in isolated
uv venv):dorks_hunter,CMSeeK,EmailHarvester,Spoofy,SSTImap,gato,regulator,reconftw_ai,getjswords.py - Go (latest, min ~1.21) - Primary binary language for ~55 security tools installed via
go install @latest
Runtime
- Linux (Debian/Ubuntu/RHEL/Arch) or macOS (Apple Silicon / Intel)
- Docker: Ubuntu 24.04 base image (
Docker/Dockerfile) - ARM64/aarch64, ARMv6l/v7l, and x86_64 all supported for Go binary installs
getopt(GNU getopt required on macOS viabrew install gnu-getopt)nproc/sysctl -n hw.ncpufor CPU core auto-detectiontimeout/gtimeout(macOS Homebrewcoreutils)gnu-sed(macOS requiresbrew install gnu-sed)gnu-coreutils(macOS requiresbrew install coreutils)- Go tools:
go install(GOPATH=$HOME/go,GOROOT=/usr/local/go) - Python tools:
uv tool installfrom GitHub (most) or PyPI (fray) - Python repo venvs:
uv venv venv && uv pip install -r requirements.txt - Lockfile: None (always installs
@latest)
Frameworks
- No framework — pure Bash with sourced module files
- Module loading order:
lib/validation.sh→lib/common.sh→lib/ui.sh→lib/parallel.sh→modules/utils.sh→modules/core.sh→modules/osint.sh→modules/subdomains.sh→modules/web.sh→modules/vulns.sh→modules/axiom.sh→modules/modes.sh - bats-core (Bash Automated Testing System)
- GNU make (
Makefile) — test, lint, format targets - shellcheck (error-level) —
make lint, pre-commit hook - shfmt (4-space indent,
-bn,-ci) —make fmt, pre-commit hook - pre-commit hooks defined in
.pre-commit-config.yaml - semgrep:
.github/workflows/semgrep.yml(CI only)
Key Dependencies
Go Tools (installed via go install @latest)
subfinder(projectdiscovery/subfinder) — passive multi-source subdomain discoverygithub-subdomains(gwen001/github-subdomains) — GitHub-based subdomain searchgitlab-subdomains(gwen001/gitlab-subdomains) — GitLab-based subdomain searchdnstake(pwnesia/dnstake) — subdomain takeover detectionpuredns(d3mondev/puredns) — mass DNS resolution with wildcard filteringdnsx(projectdiscovery/dnsx) — DNS toolkitmassdns(blechschmidt/massdns) — via repo clone + builddsieve(trickest/dsieve) — subdomain filteringenumerepo(trickest/enumerepo) — GitHub org repo enumerationgotator(Josue87/gotator) — subdomain permutationsanalyticsrelationships(Josue87/analyticsrelationships) — Google Analytics pivotingroboxtractor(Josue87/roboxtractor) — robots.txt extractorcrt(cemulus/crt) — crt.sh searchasnmap(projectdiscovery/asnmap) — ASN-to-CIDR mappingmapcidr(projectdiscovery/mapcidr) — CIDR manipulationsmap(s0md3v/smap) — passive Shodan-powered port scantlsx(projectdiscovery/tlsx) — TLS certificate harvestinghakip2host(hakluke/hakip2host) — reverse IP lookupcdncheck(projectdiscovery/cdncheck) — CDN/WAF IP classificationhakoriginfinder(hakluke/hakoriginfinder) — origin IP discovery behind CDNinscope(tomnomnom/hacks/inscope) — scope filteringcsprecon(edoardottt/csprecon) — CSP-based subdomain discoveryfavirecon(edoardottt/favirecon) — favicon-based tech reconhttpx(projectdiscovery/httpx) — multi-probe HTTP toolkitkatana(projectdiscovery/katana) — web crawlerffuf(ffuf/ffuf) — web fuzzersubjs(lc/subjs) — JavaScript URL extractorGxss(KathanP19/Gxss) — reflected XSS param finderjsluice(BishopFox/jsluice) — JS secret/URL extractorsourcemapper(denandz/sourcemapper) — JS source map extractormantra(brosck/mantra) — JS/secret scannerurlfinder(projectdiscovery/urlfinder) — URL discoveryxnLinkFinder(xnl-h4ck3r/xnLinkFinder) — via uvnmapurls(sdcampbell/nmapurls) — URL extraction from Nmap XMLnaabu(projectdiscovery/naabu) — fast port scannerVhostFinder(wdahlenburg/VhostFinder) — virtual host discoveryshortscan(bitquark/shortscan) — IIS short filename scannernuclei(projectdiscovery/nuclei) — template-based scannerdalfox(hahwul/dalfox) — XSS scannercrlfuzz(dwisiswant0/crlfuzz) — CRLF injection scannerWeb-Cache-Vulnerability-Scanner(Hackmanit) — web cache poisoningTInjA(Hackmanit/TInjA) — SSTI scannertoxicache(xhzeem/toxicache) — web cache poisoningsecond-order(mhmdiaa/second-order) — broken link/second-order injections3scanner(sa7mon/s3scanner) — S3/GCS/Azure Blob misconfigurationmisconfig-mapper(intigriti/misconfig-mapper) — third-party misconfigurationsj(BishopFox/sj) — Swagger/OpenAPI analysisgrpcurl(fullstorydev/grpcurl) — gRPC reflection scannernerva(praetorian-inc/nerva) — service fingerprintingbrutus(praetorian-inc/brutus) — credential sprayingjulius(praetorian-inc/julius) — LLM endpoint probetitus(praetorian-inc/titus) — secrets enginenotify(projectdiscovery/notify) — multi-channel notificationsinteractsh-client(projectdiscovery/interactsh) — OOB callback servergf(tomnomnom/gf) — URL pattern grepanew(tomnomnom/anew) — append new lines onlyunfurl(tomnomnom/unfurl) — URL parserqsreplace(tomnomnom/qsreplace) — querystring replacergitdorks_go(damit5/gitdorks_go) — GitHub dork searchgithub-endpoints(gwen001/github-endpoints) — GitHub endpoint discoverycent(xm1k3/cent) — nuclei template managertrufflehog(trufflesecurity/trufflehog) — secrets scanner (viago install)brutespray(x90skysn3k/brutespray) — service credential spraying
Python Tools (installed via uv tool install)
dnsvalidator(vortexau/dnsvalidator) — DNS resolver validationinterlace(pry0cc/interlace) — parallel command runnerwafw00f(EnableSecurity/wafw00f) — WAF fingerprintingcommix(commixproject/commix) — command injection scannerwaymore(xnl-h4ck3r/waymore) — passive URL collectionurless(xnl-h4ck3r/urless) — URL deduplicationghauri(r0oth3x49/ghauri) — SQLi scanner (optional)xnLinkFinder(xnl-h4ck3r/xnLinkFinder) — deep link finderxnldorker(xnl-h4ck3r/xnldorker) — Google dorkerporch-pirate(MandConsultingGroup/porch-pirate) — Postman API leaksp1radup(iambouali/p1radup) — URL deduplicationsubwiz(hadriansecurity/subwiz) — ML-based subdomain predictionarjun(s0md3v/Arjun) — parameter discoverygqlspection(doyensec/GQLSpection) — GraphQL deep introspectionpostleaksNg(six2dez/postleaksNG) — Postman public leak searchcewler(roys/cewler) — web wordlist generatorfray(dalisecurity/fray) — WAF-aware payload testing (PyPI)
Repo-Clone Tools (Python venvs, run via venv/bin/python3)
dorks_hunter(six2dez/dorks_hunter) — Google dork automationCMSeeK(Tuhinshubhra/CMSeeK) — CMS fingerprintingcloud_enum(initstring/cloud_enum) — AWS/GCP/Azure bucket enumerationEmailHarvester(maldevel/EmailHarvester) — email harvestingSwaggerSpy(UndeadSec/SwaggerSpy) — Swagger endpoint leak detectionLeakSearch(JoelGMSec/LeakSearch) — credential leak searchSpoofy(MattKeeley/Spoofy) — email spoofing checkmsftrecon(Arcanum-Sec/msftrecon) — Microsoft tenant reconScopify(Arcanum-Sec/Scopify) — scope managementregulator(cramppet/regulator) — regex-based subdomain permutationsSSTImap(vladko312/SSTImap) — SSTI scanner (alternative engine)gato(praetorian-inc/gato) — GitHub Actions audit
Repo-Clone Tools (Go build)
ghleaks(dinosn/ghleaks) — GitHub-wide secret searchnomore403(devploit/nomore403) — 403 bypassffufPostprocessing(Damian89/ffufPostprocessing) — ffuf result analysisJSA(w9w/JSA) — JS analysisultimate-nmap-parser(shifty0g/ultimate-nmap-parser) — Nmap XML parser
System-Level Tools (apt/brew/yum)
nmap— active port scanningmassdns— DNS resolver (also cloned + built from source)jq— JSON processing throughout all modulesexiftool(perl-Image-ExifTool) — metadata extractionwhois— domain registration lookupsqlmap— SQL injection (system or via repo clone)testssl.sh(testssl/testssl.sh) — TLS/SSL misconfiguration testingmedusa— credential brute-force (system install)shodanCLI — installed viauv tool install shodan
Rust Tools
smugglex(Cargo) — HTTP request smuggling detection- Rustup installed from
https://sh.rustup.rs
Configuration
reconftw.cfg— sourced after CLI parsing; all feature flags, rate limits, timeouts, wordlist paths, API keys, thread countssecrets.cfg(gitignored, auto-sourced) — API keys and tokens separated from main configsecrets.cfg.example— template showing all supported secret vars- Feature flags:
OSINT=true,SUBDOMAINS_GENERAL=true,VULNS_GENERAL=false, etc. - Rate limits:
HTTPX_RATELIMIT=150,NUCLEI_RATELIMIT=150,FFUF_RATELIMIT=0 - Thread counts: auto-scaled via
AVAILABLE_CORES=$(nproc)with multipliers per tool - Timeouts: per-tool in seconds or minutes (
CMSSCAN_TIMEOUT=3600,SUBFINDER_ENUM_TIMEOUT=180) - Wordlist paths:
fuzz_wordlist,lfi_wordlist,subs_wordlistetc. under${WORDLISTS_DIR} - Output:
EXPORT_FORMAT,AI_REPORT_TYPE,ASSET_STORE - GNU
getoptlong options, parsed inreconftw.shwhile/case loop - All CLI overrides use
CLI_*pattern and are re-applied afterreconftw.cfgis sourced - Full list from
getoptcall:domain,list,recon,subdomains,passive,all,web,osint,zen,deep,help,vps,vps-count,ai,check-tools,health-check,quick-rescan,incremental,adaptive-rate,dry-run,parallel,no-parallel,monitor,monitor-interval,monitor-cycles,refresh-cache,gen-resolvers,force,export,report-only,no-report,parallel-log,quiet,verbose,no-color,log-format,show-cache,banner,no-banner,legal SHODAN_API_KEY,WHOISXML_API,PDCP_API_KEY,XSS_SERVER,COLLAB_SERVER— preferred over config fileGOROOT,GOPATH,PATH— extended byreconftw.cfgfor Go and Rust binariesLOGFILE— per-target log pathconfig/reconftw_full.cfg— full-scan presetconfig/reconftw_quick.cfg— quick-scan presetconfig/reconftw_stealth.cfg— low-noise preset
Build
- Default:
go1.23.6(fetches latest fromhttps://go.dev/VERSION?m=text) - Installed to
/usr/local/go; setinstall_golang=falsein config to skip - Minimum: Python 3.7 (enforced in
install_yum()) - Virtual environments per tool via
uv venv - Root venv at
.venv/forgetjswords.pyand similar helpers
Platform Requirements
- Bash ≥ 4.3 (for
wait -nused inlib/parallel.sh) - Go ≥ 1.21 (tools use SIV module paths like
/v2,/v3) - Python ≥ 3.7
uvpackage manager- Rust / Cargo (for
smugglex) - GNU coreutils, getopt, sed (macOS only via Homebrew)
- ~5GB free disk space for Go cache, tools, and repos
- ~1GB RAM minimum (Go compilation)
- Base image:
ubuntu:24.04 - Build arg
INSTALL_AXIOM=true(default) installs axiom fleet tooling - Ports 85-90 exposed (for headless browser tooling)
- Runs as root (required for raw socket operations by some tools)
- Health check:
./reconftw.sh --health-check
Conventions
Shell Settings
Source Guard Pattern
lib/common.sh:[[ -n "$_COMMON_SH_LOADED" ]] && return 0lib/parallel.sh:[[ -n "$_PARALLEL_SH_LOADED" ]] && return 0lib/ui.sh:[[ -n "${_UI_SH_LOADED:-}" ]] && return 0
Function Naming
- Public module functions:
snake_caseprefixed with module context (sub_passive,sub_crt,geo_info) - Private helpers:
_snake_caseprefix (_print_status,_print_error,_print_module_start,_parallel_emit_job_output) - UI layer:
ui_prefix (ui_init,ui_header,ui_summary,ui_batch_end) - Lifecycle wrappers:
start_func/end_func(call these at top/bottom of every recon function) - Validation functions:
validate_*/sanitize_*(defined inlib/validation.shandmodules/utils.sh)
Variable Naming
- Config flags:
SUBPASSIVE,SUBCRT,PARALLEL_MODE,OUTPUT_VERBOSITY - Runtime state:
LOGFILE,SCRIPTPATH,DIFF,DRY_RUN,AXIOM - Error codes:
E_SUCCESS=0,E_INVALID_DOMAIN=20,E_INVALID_IP=21(readonly, defined inlib/validation.sh)
CLI Flag Pattern
Output / UI Conventions
OUTPUT_VERBOSITY=0(quiet): only errors/FAIL printedOUTPUT_VERBOSITY=1(normal, default): OK/WARN/FAIL/SKIP status linesOUTPUT_VERBOSITY=2(verbose): all of the above + INFO messages + start_func messages
Function Lifecycle (start_func / end_func)
start_func name desc— logs to LOGFILE, sets per-function start timestamp, emits INFO at verbosity >= 2end_func message name [status]— touches checkpoint file, calculates elapsed time, calls_print_statusskip_notification reason— emits SKIP/CACHE badge; reasons:"disabled","mode","processed","processed-visible","noinput"
File Checkpointing (Resumability)
end_funccreates the checkpoint:touch "$called_fn_dir/.${fn}"- DIFF mode (
DIFF=true) bypasses checkpoint — forces re-execution - Helper
should_run()inlib/common.shprovides a cleaner gate:if should_run "FLAG_VAR"; then
Error Handling
E_SUCCESS=0,E_GENERAL=1,E_MISSING_DEP=2,E_INVALID_INPUT=3
Validation Functions
| Function | Purpose |
|---|---|
validate_domain() |
RFC domain check + injection character rejection |
validate_ipv4() |
Octet range validation |
validate_integer() |
Numeric range check |
validate_boolean() |
Accepts true/false only (not 1/0/yes/no) |
validate_file_readable() |
Exists + readable + is-a-file |
sanitize_interlace_input() |
Removes shell metacharacters from input files (canonical in lib/validation.sh) |
sanitize_domain() |
Strips URL components, lowercases, rejects injection (in modules/utils.sh) |
is_in_scope_host() |
Anchored hostname scope check (prevents substring false positives) |
filter_in_scope_urls() |
Python3-based URL scope check (scheme, userinfo, host) |
Path and CWD Conventions
Parallel Execution
Import / Sourcing Order
Logging
- All tool output redirected to
$LOGFILE:command ... 2>>"$LOGFILE" >/dev/null - Structured JSON logging via
log_json level func message [key=val](optional,STRUCTURED_LOGGING=true) redact_secrets()scrubsREDACT_VARSandREGISTERED_SECRETSfrom log linesregister_secret "$value"must be called before logging any secret value
Comments
Architecture
System Overview
Component Responsibilities
| Component | Responsibility | File |
|---|---|---|
| Entry point & CLI parser | getopt argument parsing, config sourcing, mode dispatch | reconftw.sh |
| Mode orchestration | start/end, workflow functions (recon, passive, all, vulns, osint, subs_menu, webs_menu, zen_menu, monitor_mode) |
modules/modes.sh |
| Function lifecycle | start_func/end_func, checkpointing, logging, notifications, reporting, plugins, health check |
modules/core.sh |
| Subdomain enumeration | All sub_* functions, subtakeover, zonetransfer, s3buckets, geo_info |
modules/subdomains.sh |
| Web analysis | webprobe_full, screenshot, nuclei_check, fuzz, jschecks, urlchecks, waf_checks, and 20+ others |
modules/web.sh |
| Vulnerability scanning | xss, ssrf_checks, sqli, crlf_checks, lfi, ssti, smuggling, fuzzparams, nuclei_dast, and others |
modules/vulns.sh |
| OSINT collection | domain_info, ip_info, emails, google_dorks, github_leaks, github_actions_audit, cloud_enum_scan, etc. |
modules/osint.sh |
| Shared utilities | run_command, sed_i, deleteOutScoped, validate_config, cache_*, checkpoint_*, circuit_breaker_*, rate-limit adaption |
modules/utils.sh |
| Axiom/distributed mode | axiom_launch, axiom_shutdown, axiom_selected, resolvers_update, ipcidr_target |
modules/axiom.sh |
| Parallel execution | parallel_funcs, _throttle_jobs, job heartbeat, progress live display, log mode output |
lib/parallel.sh |
| Input validation/sanitization | sanitize_domain, sanitize_ip, validate_domain, validate_integer, _sanitize_list_entry |
lib/validation.sh |
| Shared file/counter utilities | ensure_dirs, ensure_webs_all, safe_backup, count_lines, incident tracking |
lib/common.sh |
| UI presentation layer | _print_status, _print_msg, _print_section, _print_rule, ui_header, ui_summary, TTY detection, color management, JSONL output |
lib/ui.sh |
| Configuration | All runtime settings (~350 variables); sourced after CLI parse | reconftw.cfg |
Pattern Overview
- Single process:
reconftw.shsources all libraries and modules at startup; every function lives in the same shell environment - No subshell isolation between modules — all state is shared via global variables
- File-based checkpointing:
called_fn_dir/.funcnamesentinel files prevent re-running completed functions across invocations - CLI-over-config:
reconftw.cfgprovides defaults; CLI flags setCLI_*variables that are re-applied after config sourcing to guarantee they cannot be overwritten - All external tool invocations go through
run_command()which handles dry-run mode, adaptive rate limiting, axiom dispatch, and debug logging
Layers
- Purpose: Bootstrap, macOS re-exec, module loading, getopt CLI parsing, config sourcing, CLI override re-application, mode dispatch
- Location:
reconftw.sh - Contains:
normalize_vps_count_args(), the mainwhile/casegetopt loop, the configsourcesequence, CLI override if-blocks, the finalcase $opt_modedispatch - Depends on: All libraries (sourced first), all modules (sourced second)
- Used by: End user / CI
- Purpose: Reusable utilities with no side effects; loadable independently for tests
- Location:
lib/validation.sh,lib/common.sh,lib/ui.sh,lib/parallel.sh - Contains: Input sanitization, file helpers, UI/color/progress, parallel job management
- Depends on: Nothing (source-guarded with
_*_LOADEDpattern) - Used by: All modules and reconftw.sh
- Purpose: Implement all scanning, analysis, and orchestration functions
- Location:
modules/ - Contains: All recon, vuln, OSINT, web, subdomain functions
- Depends on: Libraries (always loaded first),
reconftw.cfgvariables, external tools on PATH - Used by: modes.sh orchestrates all others; reconftw.sh dispatches to modes.sh
- Purpose: Default runtime values for ~350 flags/paths/limits; can be overridden by
secrets.cfgand custom config - Location:
reconftw.cfg, optionallysecrets.cfg, optionally$CUSTOM_CONFIG - Contains: Module enable/disable flags, tool flags, API key env-var references, paths, parallelism settings, verbosity, Axiom settings
- Depends on: Nothing
- Used by: Sourced by
reconftw.shbetween CLI parse and CLI override re-application - Purpose: Store per-target findings in a stable directory hierarchy
- Location:
Recon/<domain>/(created atstart()time bymodules/modes.sh) - Contains: Standard subdirectories listed below
- Depends on:
start()in modes.sh creates the directory tree
Data Flow
Primary Recon Request Path (-r / --recon)
Function Execution Path (every leaf module function)
Parallel Execution Path
Axiom Distributed Scan Flow
- Global bash variables throughout (no encapsulation). Config vars, target vars (
domain,dir,called_fn_dir,LOGFILE), and result counters are all globals passive()saves/restores module-enable globals before overriding them (modules/modes.sh:549-611)
Key Abstractions
- Purpose: Lifecycle wrapper around every leaf scanning function
- Examples: Used in every function in
modules/subdomains.sh,modules/web.sh,modules/vulns.sh,modules/osint.sh - Pattern:
start_func "${FUNCNAME[0]}" "description"at top;end_func "output path" "${FUNCNAME[0]}"at bottom; creates checkpoint file on end - Purpose: Prevent re-running completed functions across multiple invocations of the same target
- Location:
Recon/<domain>/.called_fn/.funcname - Pattern: Each function tests
[[ ! -f "$called_fn_dir/.${FUNCNAME[0]}" ]] || [[ $DIFF == true ]];end_funcwrites the sentinel viatouch "$called_fn_dir/.${fn}" - Purpose: Universal external-tool gate for dry-run preview, axiom dispatch, adaptive rate limiting, and debug logging
- Location:
modules/utils.sh:468 - Pattern: All tool calls inside module functions use
run_command <binary> <args>rather than direct invocation - Purpose: Allow modules to be sourced multiple times (test re-sourcing,
--source-only) without re-executing - Pattern:
[[ -n "$_FOO_LOADED" ]] && return 0at top of each lib file (lib/common.sh:6,lib/parallel.sh:6,lib/ui.sh:5,lib/validation.sh— validation uses error-code guards instead) - Purpose: Run independent module functions concurrently up to
PARALLEL_MAX_JOBS - Pattern:
parallel_funcs N func_a func_b func_c— each function spawned as a background subshell; used inrecon(),osint(),vulns()for independent groups - Purpose: Transparent axiom/local fallback wrapper — if axiom fails during a module, retries locally
- Location:
modules/modes.sh:656 - Pattern: All module calls inside
subs_menu,webs_menu,recon,passiveuse this wrapper
Entry Points
- Location:
reconftw.sh - Triggers: Direct execution (
./reconftw.sh -d example.com -r) - Responsibilities: Bootstrap, all module loading, CLI parse, config source, mode dispatch
- Location:
reconftw.sh:123-125 - Triggers:
./reconftw.sh --source-only(used by bats testsetup()blocks) - Responsibilities: Sources all modules without executing any recon
- Location:
modules/modes.sh:13 - Triggers: Called at the top of most workflow functions (
recon,subs_menu,passive,osint,zen_menu) - Responsibilities: Create output directory tree, init LOGFILE, init cache/incremental/DNS/plugins, set global
dirandcalled_fn_dir - Location:
modules/modes.sh:286 - Triggers: Called at the bottom of most workflow functions
- Responsibilities: AI report, cleanup, Faraday, screenshot diffs, plugin events, hotlist,
export_reports(), timing summary
Output Directory Structure
Verbosity and Output Controls
0(quiet): Only errors and final summary printed to terminal; banner suppressed1(normal, default): Errors + warnings printed;notification()info/good suppressed2(verbose): Allnotification()calls, PID info, full parallel output,start_funcmessages,print_timing_summarysummary: One badge line per completed parallel jobtail: LastPARALLEL_TAIL_LINES(default 20, doubled on failure) from each job's logfull: Complete captured stdout from each jobjsonl-strict: ForcesOUTPUT_VERBOSITY=0, emits only machine-readable JSONL
Architectural Constraints
- Threading: Single-threaded bash with optional background subshells via
parallel_funcs;wait -n(bash 4.3+) used for job throttling in_throttle_jobs - Global state: All config vars,
domain,dir,called_fn_dir,LOGFILE,start,runtime,DIFF,AXIOM, and hundreds of module-enable flags are module-level globals; any sourced function can read or mutate them - Circular imports: None by design — reconftw.sh sources libs first, then modules in explicit dependency order (
utils.sh→core.sh→osint.sh→subdomains.sh→web.sh→vulns.sh→axiom.sh→modes.sh) - macOS bash version: reconftw.sh re-execs itself under Homebrew bash ≥ 4 on macOS (system bash is 3.2);
lib/parallel.shrequires bash 4.3+ forwait -n - Working directory:
start()callscd "$dir"(the per-target output dir) before any module function runs; all relative paths inside modules resolve against the target dir.reconftw.shcapturesstartdir=${PWD}before this - No subshell isolation per module: Modules are sourced functions, not subprocess commands. A
returninside a module returns from the function; anexitwould kill the whole shell
Anti-Patterns
Direct external tool calls without run_command
Writing checkpoint files manually
Skipping the [[ ! -f "$called_fn_dir/.${FUNCNAME[0]}" ]] || [[ $DIFF == true ]] guard
Overriding config globals without save/restore in workflow functions
Error Handling
- ERR trap in
start()logs function name, line number, and command to$LOGFILEand callsexplain_err()(modules/modes.sh:140) - Non-zero exit from
parallel_funcsincrementsRECON_OSINT_PARALLEL_FAILURESand setsRECON_PARTIAL_RUN=true run_module_with_axiom_failovercatches axiom mid-run failures and retries locally- Circuit-breaker helpers (
circuit_breaker_is_open,circuit_breaker_record_failure) inmodules/utils.sh:1190for persistent tool failures
Cross-Cutting Concerns
Project Skills
No project skills found. Add skills to any of: .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/, or .codex/skills/ with a SKILL.md index file.
GSD Workflow Enforcement
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
/gsd-quickfor small fixes, doc updates, and ad-hoc tasks/gsd-debugfor investigation and bug fixing/gsd-execute-phasefor planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
Developer Profile
Profile not yet configured. Run
/gsd-profile-userto generate your developer profile. This section is managed bygenerate-claude-profile-- do not edit manually.