Architecture

Architecture

Kraken is a single-process, interactive Bash orchestrator. The entry point sources a small set of helper libraries, then loops on a menu that dispatches to independent tentacle modules.

Layout

kraken.sh                   # entry point, orchestrator (~130 lines)
lib/
  core.sh                   # version, globals, TTY colors, kraken_valid_target
  logger.sh                 # log_* helpers + kraken.log mirror
  installer.sh              # command/repo checks, prompts
  ui.sh                     # banner, menu, config view
  session.sh                # interactive session bootstrap, connectivity
  modules/
    recon.sh                # DNS, subdomains, WHOIS, reverse DNS
    scan.sh                 # nmap + /dev/tcp fallback
    web.sh                  # headers, directories, tech, robots
    vuln.sh                 # SSL/TLS, methods, security headers
    report.sh               # aggregate session into text + Markdown
docs/                       # ARCHITECTURE, ADDING_A_MODULE, IMPROVEMENTS
.github/                    # CI workflow, issue / PR templates

Boot sequence

1. kraken.sh runs with set -uo pipefail (no -e, see below).

2. It computes KRAKEN_ROOT from BASH_SOURCE[0] and sources every library file. Each library guards against double-sourcing with a KRAKEN_*_LOADED sentinel:

   if [[ -n "${KRAKEN_CORE_LOADED:-}" ]]; then
       return 0
   fi
   KRAKEN_CORE_LOADED=1

3. CLI parsing handles --help / --version, then:

   • root warning ($EUID -eq 0),
   • dependency check (nmap, curl, host),
   • interactive session bootstrap (new / resume / auto),
   • main_loop until the user types Q.

Why no set -e

The main loop is interactive. A non-zero exit code from any wrapped tool (a failed nmap scan, a 5xx from curl) is tolerable, the operator wants to read the message and try again. With set -e those exit codes would tear down the whole shell. The entry point therefore uses set -uo pipefail only:

• -u catches typos in variable names.
• pipefail propagates failures inside pipelines.

Module functions handle their own error paths through log_warn / log_error and return, never exit.

Color palette

lib/core.sh detects an interactive TTY ([[ -t 1 ]] plus a tput colors check) and only emits escape codes in that case. When stdout is a pipe or a non-color terminal, the color variables expand to empty strings, so logs stay readable when piped to tee or a file.

Logging

lib/logger.sh exposes five level helpers backed by a single private formatter:

Function	Tag	Stream	Mirrored to kraken.log
log_step	[*] magenta	stdout	yes
log_info	[i] blue	stdout	yes
log_success	[+] green	stdout	yes
log_warn	[!] yellow	stdout	yes
log_error	[x] red	stderr	yes

All messages are timestamped (%Y-%m-%d %H:%M:%S). When a session directory exists, each line is also appended, color-stripped, to ${KRAKEN_OUTPUT_DIR}/kraken.log.

Module contract

Every module file must:

1. Live under lib/modules/<name>.sh.
2. Start with a KRAKEN_MODULE_<NAME>_LOADED guard.
3. Expose exactly one public entry point named kraken_<name>_run, wired into the menu via handle_selection in kraken.sh.
4. Write output under ${KRAKEN_OUTPUT_DIR}/<name>_<target>/.
5. Use the shared helpers (prompt_value, ensure_command, kraken_valid_target, log_*).

Private helpers are prefixed with _kraken_<name>_ to avoid collisions across modules. See Extending Kraken.

Input validation

kraken_valid_target in lib/core.sh is the single gate for user-supplied targets. It rejects empty input, whitespace and shell metacharacters, and requires host-legal characters only. Recon, scan, vuln and web all validate before invoking any external tool, so junk never reaches nmap / curl / host.

External dependencies

Layer	Dependency	Used by
Shell	bash ≥ 4.0	everywhere
Core utils	coreutils, findutils	session, reporting
Reachability	ping	test_connectivity
DNS / WHOIS	dig, host, whois	recon module
Recon	subfinder	recon module
Scanning	nmap, /dev/tcp	scan module
Web	curl	web, vuln modules
TLS	openssl	vuln module

All external commands are guarded, missing tools trigger a warning instead of aborting the session.

Continuous integration

.github/workflows/ci.yml runs three jobs on every push and PR:

• shellcheck (warning severity, SC1091/SC2034 excluded, mirrored in the repo .shellcheckrc),
• bash -n syntax check across all *.sh files,
• smoke test that sources the whole chain and asserts every public function is defined, then exercises --help / --version.