illdan

illdan is a dependency-free, single-binary service discovery tool for authorized internal network audits.

The name comes from Korean 일단: both “first step” and “let’s first take a look.” illdan starts with a safe, portable first look at hidden hosts, unknown devices, and exposed TCP services, then leaves deliberate follow-up steps to the operator.

Status: initial v0.1.0 release. The project is usable for controlled local/lab validation and remains early-stage; interfaces and output formats may change before a later stable release.

Why illdan exists

illdan is not trying to be the fastest port scanner or a replacement for Nmap. It is designed for situations where an auditor or internal security administrator wants a small, portable discovery tool that:

• runs as a single Go binary
• avoids external scanner/runtime/driver dependencies
• works without raw packet privileges
• discovers TCP services even when ICMP is blocked
• records scan configuration and evidence in a result bundle
• can generate reviewable handoff commands for deeper follow-up tools without executing them

Safety model

illdan is for authorized defensive use only.

Before scanning, define the intended scope and keep the run bounded:

./bin/illdan scan 10.0.0.0/24 \
  --scope 10.0.0.0/24 \
  --ports seed \
  --max-targets 4096 \
  --rate 200 \
  --concurrency 128 \
  --timeout 800ms \
  --out ./results/internal-discovery

Important safety defaults and constraints:

• --scope rejects targets outside the authorized range.
• --max-targets rejects oversized target expansion before scanning.
• --icmp filter is rejected in the MVP; ICMP is not used to exclude silent hosts.
• wildcard/tarpit control-port checks keep control opens separate from normal service opens.
• external handoff modes write artifacts only; they do not run external tools.

See SECURITY.md for reporting and safe reproduction guidance.

Current capabilities

• commands: illdan version, illdan scan <targets...>
• targets: single IPs, CIDRs, and @file target lists
• port specs: seed, comma lists, ranges, and top-100 aliasing the current seed set
• bounded target expansion with --max-targets
• TCP connect-first service discovery
• --icmp off|hint; --icmp filter is intentionally unsupported in the MVP
• --profile conservative|normal|fast|audit
• --concurrency, --rate, --timeout, --retries
• append-only JSONL resume state
• wildcard/tarpit control-port checks
• result bundle: summary.json, events.jsonl, hosts.csv, config.json, README.txt, result.zip
• external CLI handoff artifacts: --handoff none|nmap|generic

Non-goals for the MVP

• SYN scan
• ARP scan
• UDP scan
• OS fingerprinting
• vulnerability checks or exploit verification
• credential attacks or exploit payloads
• bundling or invoking Nmap/RustScan/naabu by default
• internet mass-scanning positioning

Build

Requires Go 1.23 or newer.

go build -o ./bin/illdan ./cmd/illdan
./bin/illdan version

Usage

./bin/illdan --help
./bin/illdan version
./bin/illdan scan <targets...> [flags]

Example discovery scan:

./bin/illdan scan 10.0.0.0/24 \
  --scope 10.0.0.0/24 \
  --ports seed \
  --profile normal \
  --timeout 800ms \
  --concurrency 128 \
  --icmp hint \
  --out ./results/internal-discovery

Target lists can be supplied from files:

# targets.txt
10.0.0.12
10.0.0.25
10.0.1.0/28  # comments are allowed

./bin/illdan scan @targets.txt --scope 10.0.0.0/16 --ports 22,80,443

Output bundle

Each scan writes an output directory. The default is illdan-results/.

summary.json   machine-readable summary
config.json    effective scan configuration
events.jsonl   append-only per-attempt event log
hosts.csv      host/port summary for spreadsheet use
README.txt     human-readable scan report
result.zip     portable bundle containing the above files
handoff/       optional external CLI handoff artifacts

The result records the target set, effective scope, whether scope was defaulted, ports, timeout, retries, concurrency, rate, ICMP mode, wildcard check settings, and handoff metadata.

Nmap handoff

To hand open non-control service results to Nmap for a deeper authorized follow-up scan:

./bin/illdan scan 10.0.0.0/24 \
  --scope 10.0.0.0/24 \
  --ports seed \
  --handoff nmap \
  --out ./results/internal-discovery

When open service ports are found, this writes:

handoff/nmap-targets.txt
handoff/nmap-services.tsv
handoff/nmap-commands.sh
handoff/nmap-commands.ps1

Generated commands use TCP connect and version detection by default:

nmap -sT -sV -Pn -p 80,443 -oA './results/internal-discovery/handoff/nmap-10.0.0.12' '10.0.0.12'

illdan does not bundle, install, or run Nmap. Review scope and authorization before executing generated commands.

Generic handoff

Generic command templates are also supported:

./bin/illdan scan 10.0.0.0/24 \
  --scope 10.0.0.0/24 \
  --handoff generic \
  --handoff-template 'tool --host {host} --ports {ports} --out {tool_output_base}' \
  --out ./results/internal-discovery

Supported placeholders:

{host}
{ports}
{port}
{output_dir}
{tool_output_base}

Templates containing {port} expand once per open service port. Templates without {port} are generated once per discovered host and can use {ports}.

Development

Run the local quality checks:

go test ./...
go vet ./cmd/illdan
go build ./cmd/illdan

A loopback smoke path is covered by tests when the environment permits local TCP listeners.

Roadmap

Near-term maintenance work is focused on making defensive use safer and easier to review:

• publish cross-platform release artifacts from GitHub Actions
• add a dry-run scan plan so operators can review expanded targets and ports before probing
• strengthen resume/session metadata so resumed scans reload the original scope and scan settings safely
• expand tests around scope guards, handoff generation, output bundles, and edge-case target parsing
• add controlled lab examples for defenders using loopback or private test networks
• improve documentation for authorized internal audits and safe follow-up workflows

License

MIT. See LICENSE.

Design notes

See SPEC.md for the design rationale and MVP scope.