nokizaru

Web recon TUI Purpose-built for bug bounty/web app penetration tests

Nokizaru

Nokizaru is a CLI tool purpose-built for enumerating the core web recon surface. Its goal is to provide a sufficiently expansive, high-signal overview of a target quickly, subverting the need to reach for heavier OSINT suites. Instead of running several tools in sequence, Nokizaru aims to produce comparable recon results with a single full-scan command. The ideal use case is collecting relevant information on a web target during the recon phase of a bug bounty or web app pentest engagement. As such, the primary audience is security researchers (not CTI analysts who may still prefer larger, more comprehensive OSINT suites).

[!CAUTION]

Nokizaru is intended for authorized security testing and research. Always ensure you have explicit permission to scan targets you do not own.


Architecture

Nokizaru runs a full web recon pass with shared target context, bounded or adaptive module execution, and graceful degradation when targets are slow, hostile, or heavily canonicalized. Healthy full directory scans complete their finite plan without a fixed total budget.

Context-Aware Scanning Pipeline

  • Headers -> Target Profile: response headers shape later scan behavior, including redirect and canonical host hints
  • Custom Headers: repeatable -H/--header values are reused across in-scope web requests without printing secrets back to stdout
  • Re-Anchoring: crawler and directory scans can automatically move to the effective in-scope URL, such as HTTP -> HTTPS or canonical same-scope hosts
  • Cross-Module Feeds: modules inform each other instead of running in isolation. Wayback history, architecture-fingerprinted tech paths, crawler finds, and open alternate-origin web ports all seed directory and crawler checks; TLS certificate SANs and DNS records (NS/MX/CNAME) seed subdomain enumeration
  • Adversarial Awareness: directory enumeration names the defense it meets (WAF, soft-404 wildcard, rate limiting, auth wall), adapts to a detected wall, and stops early when it persists rather than flooding the wordlist. Defensive noise stays inspectable in exports while stdout favors actionable paths
  • Port Scan Context: port checks are native TCP probes with lightweight service/category/TLS/HTTP/exposure hints
  • Wayback Snapshots: host-scoped archive history selects up to five snapshots each near 3 months, 6 months, and 1 year, then fills a 50-result cap with high-signal changes

Installation

Nokizaru builds to a single binary with no runtime dependencies.

Nix (recommended)

The root flake targets aarch64-linux and x86_64-linux with nixpkgs pinned to a Crystal 1.21.1 toolchain, giving a reproducible binary with its data embedded and its system libraries managed by Nix.

Install it permanently into your profile:

nix profile install github:hakkuri01/nokizaru
nokizaru --help

Or run it once without installing:

nix run github:hakkuri01/nokizaru -- --full --target https://example.com

For development in Nix, nix develop provides Crystal, shards, just, OpenSSL, and the pinned Ameba; the gate (just verify) and nix flake check run offline. See CONTRIBUTING.md for the full development workflow.

Build From Source (Git Clone)

On platforms without Nix (including macOS), build the binary with the Crystal compiler. Requires Crystal >= 1.21.1.

git clone https://github.com/hakkuri01/nokizaru.git
cd nokizaru
crystal build --release src/nokizaru.cr -o bin/nokizaru
./bin/nokizaru --help

Put bin/nokizaru on your PATH. That is all an operator needs; contributors setting up a development environment should follow the pinned toolchain in CONTRIBUTING.md.


Configuration

Subdomain Providers

Nokizaru queries a curated set of mature, reliable sources rather than every source in existence. The keyless core runs out of the box; key-enriched sources run only when their key is present, and a missing key skips just that source.

Provider Source API key
crt.sh Certificate Transparency (Postgres) none
AnubisDB Passive DNS none
CertSpotter Certificate Transparency none
Digitorus Certificate Transparency none
HackerTarget Passive DNS none
RapidDNS Passive DNS none
UrlScan URL / scan search none
Wayback Archived URLs none
AlienVault Passive DNS (OTX) NK_ALIENVAULT_KEY
BeVigil Mobile-app OSINT NK_BEVIGIL_KEY
VirusTotal Passive DNS NK_VT_KEY
Shodan Internet scan NK_SHODAN_KEY
Chaos ProjectDiscovery DNS NK_CHAOS_KEY
Censys Certificate search NK_CENSYS_API_ID + NK_CENSYS_API_SECRET
SecurityTrails DNS dataset NK_SECURITYTRAILS_KEY
GitHub Public code search NK_GITHUB_TOKEN
GitLab Public code search NK_GITLAB_TOKEN

crt.sh is queried over its certificate-transparency Postgres backend (crt.sh:5432) for reliable, complete results, falling back to its HTTP endpoint if the database is unreachable (operators behind restrictive egress should allow that port for best results). Wayback still enriches results but is left out of the provider-health summary: the Internet Archive throttles it aggressively server-side, so its frequent timeouts reflect their load management, not a Nokizaru fault.

API Keys

Key-enriched providers use optional API keys; a missing key skips only that provider. Architecture fingerprinting runs locally with no key and is simply enriched by a Wappalyzer key when one is present.

Environment Variables

Keys are read from environment variables if they are set; otherwise they are loaded from ${XDG_DATA_HOME:-$HOME/.local/share}/nokizaru/keys.json.

NK_ALIENVAULT_KEY, NK_BEVIGIL_KEY, NK_CENSYS_API_ID, NK_CENSYS_API_SECRET, NK_CHAOS_KEY,
NK_GITHUB_TOKEN, NK_GITLAB_TOKEN, NK_SECURITYTRAILS_KEY, NK_SHODAN_KEY, NK_VT_KEY,
NK_WAPPALYZER_KEY

# Example :
export NK_SHODAN_KEY="kl32lcdqwcdfv"

Saved Keys

Use -k to add keys, saved automatically in the user data directory. With only the key name, Nokizaru prompts for the key without echoing it (or reads it from piped stdin), so it stays out of your shell history.

# Usage
nokizaru -k '<API NAME>'

Valid Keys : 'alienvault', 'bevigil', 'censys_api_id', 'censys_api_secret', 'chaos', 'github', 'gitlab', 'securitytrails', 'shodan', 'virustotal', 'wappalyzer'

# Example :
nokizaru -k shodan

Path = ${XDG_DATA_HOME:-$HOME/.local/share}/nokizaru/keys.json

JSON Config File

The default config file is ${XDG_CONFIG_HOME:-$HOME/.config}/nokizaru/config.json.

{
  "common": {
    "timeout": 30,
    "dns_servers": "8.8.8.8, 8.8.4.4, 1.1.1.1, 1.0.0.1"
  },
  "ssl_cert": {
    "ssl_port": 443
  },
  "port_scan": {
    "threads": 50
  },
  "dir_enum": {
    "threads": 50,
    "redirect": false,
    "extension": ""
  }
}

Usage

Nokizaru - Recon Refined

Arguments:
  -h, --help       Show this help message and exit
  -v, --version    Show version number and exit
  --target TARGET  Target (http[s]://host[:port])
  --headers        Header Information
  --sslinfo        SSL Certificate Information
  --whois          Whois Lookup
  --crawl          Crawl Target
  --dns            DNS Enumeration
  --sub            Sub-Domain Enumeration
  --arch           Architecture Fingerprinting
  --dir            Directory Search
  --wayback        Wayback Snapshots
  --ps             Fast Port Scan
  --full           Full Recon
  --no-[MODULE]    Skip specified modules above during full scan (eg. --no-dir)
  --export         Write results to export directory
  --tui            Force the interactive dashboard (and the command form)
  --headless       Run with no TUI or terminal: JSON on stdout, progress on stderr

Extra Options:
  -nb          Hide Banner
  -dt DT       Number of threads for directory enum [ Default : 50 ]
  -pt PT       Port scan concurrency [ Default : 50 ]
  -p PORTS     Port scan ports [ Example : 80,443,1000-65535 ]
  -T T         Base timeout / module budget [ Default : 30.0 ]
  -w W         Wordlist size (small, medium, large) or custom path [ Default : medium ]
  -H, --header HEADER  Add custom request header (repeatable)
  -r           Follow redirects during directory enum [ Default : False ]
  --insecure   Skip TLS certificate verification for the target [ Default : False ]
  -sp SP       Specify SSL Port [ Default : 443 ]
  -d D         Custom DNS Servers [ Default : 8.8.8.8,8.8.4.4,1.1.1.1,1.0.0.1 ]
  -e E         File Extension(s) (comma separated) [ Example : txt,xml,php,etc. ]
  -o O         Export Format(s) (comma-separated) [ Default : txt,json,html ]
  -cd CD       Export directory for this run (requires --export)
  -of OF       Export filename base for this run (requires --export)
  -k K         Add API key, prompted without echo [ Example : shodan ]

Examples

# Full scan
nokizaru --full --target https://example.com

# Directory enumeration with extensions and a custom wordlist
nokizaru --dir --target https://example.com -e txt,php -w /path/to/wordlist

# Directory enumeration with a curated wordlist size
nokizaru --dir --target https://example.com -w large

# Port scan a custom port set
nokizaru --ps --target https://example.com -p 80,443,8000-8010

# Authenticated crawl + dir enum with a session cookie
nokizaru --crawl --dir --target https://example.com \
  -H 'Cookie: PHPSESSID=abc123; uid=52' \
  -H 'X-Role: admin'

Custom headers are applied only to in-scope target requests, and only to the target's own origin: a sibling host that is in scope (a CDN, a status page, a historic subdomain from the archive) is fetched without them. Nokizaru does not echo supplied header values back in module banners, and redacts a value a target reflects into a response header so it stays out of stdout and the exports.

TLS certificates are verified by default on every request. --insecure turns verification off for the target you named, which a self-signed or expired certificate needs; third-party services (subdomain providers, the archive, RDAP) stay verified either way.

Directory enumeration ships curated small (2K), medium (5K), and large (10K) wordlists, embedded in the binary. medium is the default; -w also accepts any custom wordlist path.

Interactive Dashboard

On a terminal, Nokizaru runs as a full-screen app. There are two ways in:

  • Bare launch (nokizaru, no scan flags): an opening screen reveals the banner and wordmark; press any key to reach a vim-style command form that collects the target, the modules, and the option and export switches, building a live nokizaru … command at the foot. enter runs the scan.
  • Power-user override (nokizaru <scan args>, e.g. nokizaru --full --target https://example.com): skips the opener and the form and launches straight into the running dashboard. Press q twice (qq) to drop back to the terminal and run another scan. Add --tui to force the command form instead, prefilled from your flags.

Results stream into one tab per module, plus a Summary tab. When a scan finishes, browse the tabs. Results are not printed to the terminal on exit; use --export to save them.

Mode Key Action
Form (NORMAL) j/k, ↑/↓ Move between fields
Form (NORMAL) ←/→ Move across the module chips
Form (NORMAL) space Toggle the field or focused module
Form (NORMAL) i Edit a text or number field
Form (NORMAL) h Open the flag and key reference (q or h closes it)
Form (NORMAL) enter Run the scan
Form (NORMAL) q Quit
Form (INSERT) type, ←/→, home/end Edit; enter runs, esc returns to NORMAL
Dashboard tab/shift+tab, h/l, ←/→, 1-9/0 Switch module tab
Dashboard j/k, ctrl+d/ctrl+u, pgdn/pgup, g/G Scroll the results within the pane
Dashboard f Follow the running module
Dashboard q Interactive launch: back to the form (stops a running scan). Power-user launch: press again to exit to the terminal
Anywhere ctrl+c Quit

The app does not capture the mouse, so a plain drag selects and copies text, and the wheel scrolls the results. Piped or redirected runs (for example nokizaru --full --target https://example.com --export | tee scan.txt) skip the app and print the classic line output; for machine-readable output, use headless mode.

Headless Mode

--headless runs the same scan with no TUI and no terminal, for scripts, CI, and AI-agent workflows. It takes the same flags as any other run and wins over the dashboard even on a terminal.

  • stdout carries only the result: the run as JSON, the same shape as the JSON export, written when the scan finishes. With --export, the export files are written instead (narrowed by -o, placed by -cd and -of) and stdout stays empty.
  • stderr carries one plain line per module event ([dir] running, [dir] done, [sub] skipped: <reason>, [ps] failed: <reason>), then the completion time, the export directory when exporting, and any error: line.
  • Exit code: 0 when the scan completed, 1 when it cannot run (no modules, a missing or invalid target, a non-positive number, an export failure), 2 for an unknown flag or a malformed value, 130 when interrupted. A module's own errors, such as an unreachable target, are recorded in its JSON and do not change the exit code.
  • Interrupts (SIGINT, SIGTERM, SIGHUP) stop the scan cooperatively: nothing new starts, the module in flight finishes or reaches its time budget, and the partial result is still written. A second signal exits at once with no output.
# Full recon for a pipeline: JSON on stdout, progress on stderr
nokizaru --headless --full --target https://example.com | jq '.findings'

# Write JSON and HTML exports; stderr names the export directory
nokizaru --headless --dir --ps --target https://example.com --export -o json,html

Output / Exports

Scan results are not persistent by default, although Nokizaru maintains its configuration, key store, and runtime log. If you specify --export, it writes TXT, JSON, and HTML reports unless you narrow formats with -o.

By default, exports are written to:

${XDG_DATA_HOME:-$HOME/.local/share}/nokizaru/exports/<hostname>/
├── YYYY-MM-DD_HH-MM-SS.txt
├── YYYY-MM-DD_HH-MM-SS.json
└── YYYY-MM-DD_HH-MM-SS.html

Exports are grouped by hostname and use timestamped filenames. Override the directory with -cd or the filename base with -of.


Roadmap

  • Pause and resume a running scan: a dashboard key holds the scan at its next unit of work (the runner starts no new module, directory enumeration admits no new candidate, the port scan starts no new probe) and a second press resumes it where it left off. Today the dashboard can only stop a scan.
  • Raise or lower concurrency live: change the directory enumeration (-dt) and port scan (-pt) limits from the dashboard while the scan runs. Directory enumeration already adapts its concurrency under pressure, so the new value becomes the ceiling that adaptation works under.
  • Add or remove a filter mid-run: status and size filters for directory enumeration results (Nokizaru has none today), set or cleared from the dashboard while the scan runs, so a noisy class of responses drops out of the results and the export without a restart.
  • HTTP/2: Nokizaru speaks HTTP/1.1 today. The plan is to negotiate HTTP/2 over TLS (ALPN) when the target offers it and fall back to HTTP/1.1, for the requests that go to the target (headers, architecture fingerprinting, crawler, directory enumeration). Crystal's standard library has no HTTP/2 client and Nokizaru takes no runtime shards, so the client is hand-rolled, with explicit caps on frame size, header-list size, and concurrent streams, and stays single-threaded.
  • Distribution packages: nixpkgs, Kali, Arch Linux, and Homebrew, once enough users ask for them. Until then, the flake covers Nix users and a source build covers everyone else. Packaging for any other distribution is welcome from anyone willing to maintain it.
Repository

nokizaru

Owner
Statistic
  • 1
  • 0
  • 0
  • 0
  • 1
  • 20 days ago
  • December 20, 2025
License

MIT License

Links
Synced at

Sat, 31 Oct 2026 13:49:52 GMT

Languages