GO — Healthy across the board

• Last commit 2d ago
• 15 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Naabu is a lightweight, high-performance port scanner written in Go that performs fast SYN/CONNECT/UDP scans to enumerate open ports on hosts. It specializes in reliability and simplicity for attack surface discovery in bug bounties and penetration tests, with support for IPv4/IPv6, CIDR ranges, passive Shodan integration, and NMAP service discovery chaining. Modular monorepo structure: cmd/naabu/ contains the CLI entrypoint, pkg/ holds reusable libraries (port enumeration, privilege checks, prediction models), and internal/ provides utilities (PDCP protocol, test helpers). Core scanning logic is abstracted from CLI via Go package boundaries rather than structural separation.

Security researchers, bug bounty hunters, and penetration testers who need a fast, resource-efficient port scanner to quickly identify open ports across large IP ranges as part of reconnaissance workflows.

Production-ready and actively developed. The project uses Go 1.24.0, has comprehensive CI/CD via GitHub Actions (build-test, functional-test, integration-test, release workflows), Docker support, and goreleaser configuration for binary releases. Regular dependabot updates and multiple test suites indicate active maintenance.

Low-to-moderate risk. The dependency graph is substantial (~40 direct dependencies including projectdiscovery ecosystem packages) but well-maintained. No obvious signs of abandonment given recent Go version bumps. Requires elevated privileges for raw socket operations (SYN scans), which could be a deployment constraint. Single-organization (projectdiscovery) backing reduces risk vs. personal projects.

Active development with recent Go 1.24.0 adoption, dependabot security updates, and comprehensive testing infrastructure. Multiple CI workflows validate builds, functional tests, and integration tests on each commit. Release pipeline (release-binary.yml, dockerhub-push.yml) automates binary and Docker image publishing.

git clone https://github.com/projectdiscovery/naabu.git
cd naabu
make build
# Binary created in bin/ directory
./bin/naabu -h

Daily commands:

make build          # Compiles binary to bin/naabu
make test           # Runs unit tests
make integration    # Runs integration test suite
./bin/naabu -host example.com -p 80,443,8080
./bin/naabu -list targets.txt -top-ports 1000

• cmd/naabu/main.go — Entry point for the naabu CLI application; all execution begins here and initializes the scanning workflow.
• pkg/runner/runner.go — Core orchestration engine that manages the entire port scanning lifecycle, integrating all sub-components.
• pkg/scan/scan.go — Primary scanning abstraction that defines the Scan interface and coordinates protocol-specific scan implementations.
• pkg/runner/options.go — Configuration and options structure that parametrizes all scanning behavior; essential for understanding feature flags.
• pkg/scan/connect.go — TCP connect scan implementation; one of the most commonly used scanning methods in the codebase.
• pkg/routing/router.go — Network routing and gateway resolution layer; critical for determining outbound network interfaces and paths.
• pkg/result/results.go — Result aggregation and output formatting; defines how discovered ports are stored, deduplicated, and reported.

Add a New Scanning Protocol

1. Create a new protocol scanner in pkg/scan/ (e.g., pkg/scan/mynewprotocol.go) implementing the Scan interface from pkg/scan/scan.go (pkg/scan/scan.go)
2. Implement the Scan() method and any initialization logic specific to your protocol (pkg/scan/mynewprotocol.go)
3. Register the new scanner in pkg/runner/runner.go within the scan initialization phase (pkg/runner/runner.go)
4. Add corresponding CLI flags in pkg/runner/options.go to allow users to enable/disable the protocol (pkg/runner/options.go)
5. Update pkg/protocol/protocol.go if introducing a new protocol type beyond TCP/UDP (pkg/protocol/protocol.go)

Add a New Result Enhancement (Banner Grabber, Service Detection, etc.)

1. Create enhancement logic in pkg/runner/ (following the pattern of pkg/runner/banners.go) (pkg/runner/banners.go)
2. Add a method to the Runner struct that processes results after scanning completes (pkg/runner/runner.go)
3. Call your enhancement function in the appropriate phase within Runner.Run() (pkg/runner/runner.go)
4. Add configuration options in pkg/runner/options.go to control the enhancement behavior (pkg/runner/options.go)
5. Update pkg/result/results.go if new result fields are needed to store enhancement data (pkg/result/results.go)

Add a New Output Format

1. Review the output structure in pkg/runner/output.go to understand current format handling (pkg/runner/output.go)
2. Create a new output formatter function (e.g., writeJSON, writeCSV) in pkg/runner/output.go (pkg/runner/output.go)
3. Add the format option to pkg/runner/options.go under the output flags (pkg/runner/options.go)
4. Update the output dispatch logic in pkg/runner/runner.go to call your new formatter (pkg/runner/runner.go)
5. Test with cmd/integration-test/integration-test.go to validate the new format (cmd/integration-test/integration-test.go)

Optimize Scanning Speed with Prediction

1. Review the existing prediction model in pkg/prediction/model.go and the default model data (pkg/prediction/model.go)
2. Modify or train a new model and update pkg/prediction/default_model.go with new weights/predictions (pkg/prediction/default_model.go)
3. Integrate model prediction into port scanning logic in pkg/runner/ports.go to reorder port scanning (pkg/runner/ports.go)
4. Add a CLI flag in pkg/runner/options.go to enable/disable prediction-based optimization (pkg/runner/options.go)

• Go — High concurrency with goroutines and channels; compiled binary for fast startup and deployment; excellent standard library for networking primitives
• Raw socket scanning (custom packet crafting) — Naabu uses libpcap via gopacket fork for raw packet construction; enables low-level protocol control and avoids OS TCP stack limitations for speed
• Cross-platform routing APIs (Linux iptables, Darwin/BSD route, Windows GetIpForwardTable) — Network scanning requires OS-level gateway detection; platform-specific code ensures accurate source interface selection for raw sockets
• gcache (memory cache) — Deduplication of results and fast lookup of previously discovered ports without persistent I/O

Requires elevated/root privileges for SYN scans (raw socket access); CONNECT scans work unprivileged but slower. DNS resolution depends on system resolver or custom upstream servers (configurable). Passive Shodan scans require internet connectivity. IPv6 scanning marked experimental in docs. Custom UDP payloads require precise format (see cmd/functional-test/test-data/). Rate limiting and concurrency tuning critical for large scans—sizedwaitgroup parameters must match system fd limits (projectdiscovery/fdmax integration).

• SYN stealth scanning — Naabu's primary scan method uses raw SYN packets to detect open ports without completing full TCP handshakes; understanding this is critical for privilege requirements and IDS evasion.
• Rate limiting & token bucket — Naabu uses projectdiscovery/ratelimit for pacing scans to avoid network saturation and target blacklisting; essential for reliable scanning at scale.
• Goroutine worker pools — Naabu employs sizedwaitgroup for bounded concurrent port scanning; misunderstanding concurrency limits could cause resource exhaustion or fd limit violations.
• Raw socket I/O (gopacket) — Naabu constructs and sends custom TCP/UDP packets directly via gopacket; understanding packet crafting is essential for scan customization and UDP payload handling.
• CDN/WAF bypass detection — Naabu integrates projectdiscovery/cdncheck to filter false positives from CDN-fronted hosts; critical for accurate port enumeration in modern cloud environments.
• Passive port enumeration (Shodan internetdb) — Naabu offers Shodan integration for pre-scan reconnaissance without sending traffic; useful for stealthy reconnaissance or rate-limited environments.
• File descriptor limits (fdmax) — High-speed scanning requires tuning OS fd limits; naabu integrates projectdiscovery/fdmax to auto-detect and warn on insufficient limits.

• projectdiscovery/nuclei — Companion tool for vulnerability scanning post port-discovery; naabu often feeds results into nuclei pipelines
• projectdiscovery/subfinder — Sibling reconnaissance tool for subdomain enumeration; commonly chained with naabu for full attack surface mapping
• projectdiscovery/dnsx — Integrated dependency (v1.2.3 in go.mod) for DNS port scanning and resolution; naabu uses for DNS enumeration features
• Ullaakut/nmap — Wrapped NMAP library (v3.0.6 in go.mod); naabu integrates for service detection post port-scan
• projectdiscovery/mapcidr — Dependency (v1.1.97) for CIDR range parsing and expansion; core input processing for naabu

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for pkg/routing module across all platforms

The routing module has platform-specific implementations (router_linux.go, router_windows.go, router_bsd.go, router_darwin.go) but only one router_test.go file. Each platform has different gateway detection logic that needs isolated testing. This is critical for a port scanner that relies on accurate routing information for accurate results. Current test coverage gaps could lead to platform-specific bugs going undetected.

• [ ] Review existing pkg/routing/router_test.go to understand current test patterns
• [ ] Create pkg/routing/router_linux_test.go with mocked netlink operations and /proc filesystem reads
• [ ] Create pkg/routing/router_windows_test.go with mocked WMI/Registry calls
• [ ] Create pkg/routing/router_bsd_test.go and router_darwin_test.go with platform-specific route command mocking
• [ ] Add integration tests in integration_tests/ that validate gateway detection on each OS

Add privilege escalation verification tests in pkg/privileges module

The privileges module has platform-specific implementations (privileges_linux.go, privileges_win.go, privileges_darwin.go, etc.) that validate elevated access, which is critical for raw socket operations in a port scanner. However, there are no visible tests for this module. Missing tests could allow privilege check bypasses or false positives. Add tests that verify the privilege checks work correctly on each platform.

• [ ] Create pkg/privileges/privileges_test.go with cross-platform mocking
• [ ] Add test cases for Linux (uid/gid checks, CAP_NET_RAW capability verification)
• [ ] Add test cases for Windows (Admin/SYSTEM privilege detection)
• [ ] Add test cases for BSD/Darwin (root user checks)
• [ ] Add negative test cases to ensure non-privileged detection works

Expand integration test coverage for active vs passive scanning modes

The repo has cmd/functional-test/ and cmd/integration-test/ directories with basic test infrastructure, but the testcases.txt and integration-test.go files appear minimal. Given naabu's complexity with multiple scanning modes (TCP syn, UDP, etc.) and protocol support, there's a gap in documented integration tests. Add comprehensive integration tests covering different scan scenarios.

• [ ] Review cmd/integration-test/integration-test.go and cmd/integration-test/cli.go for existing test structure
• [ ] Add integration test cases for TCP SYN scanning against known test ports
• [ ] Add integration test cases for UDP scanning verification
• [ ] Add integration test cases for scanning with proxy/SOCKS5 (pkg/runner supports this but no visible tests)
• [ ] Add integration test cases for rate limiting and timeout configurations
• [ ] Update cmd/functional-test/testcases.txt with documented expected behaviors for each test scenario

• Add unit tests for pkg/port/port.go parsing logic (currently no test file visible in structure); would improve coverage and regression protection.
• Document UDP payload format for custom scans with concrete examples in README; functional tests reference cmd/functional-test/test-data/request.txt but user-facing guide is missing.
• Implement platform-specific IPv6 privilege check in pkg/privileges/privileges_darwin.go (exists but likely incomplete vs. Linux variant); would unblock experimental IPv6 feature.

• High · Outdated Go Version in Docker Build — Dockerfile (line 2). The Dockerfile specifies golang:1.26.2-alpine for the build stage, which appears to be a future/unreleased version. This could indicate a typo or development environment issue. Additionally, the base image should pin to a specific Alpine version in build stage for reproducibility. Fix: Use a verified, stable Go version (e.g., golang:1.24.0-alpine, matching go.mod) and ensure both build and runtime base images are pinned to specific versions for reproducibility.
• Medium · Potential Privilege Escalation Risk in Privileged Operations — pkg/privileges/ directory (privileges.go and OS-specific implementations). The codebase includes privilege checking modules (pkg/privileges/) for multiple operating systems. Port scanning typically requires elevated privileges. If naabu is run with unnecessary privileges or if privilege checks are bypassed, it could lead to privilege escalation vulnerabilities. Fix: Ensure privilege checks are enforced consistently across all platforms. Implement capability-based security (CAP_NET_RAW on Linux) instead of requiring full root. Document minimum required privileges and validate at runtime.
• Medium · Hardcoded Network Configuration Paths — pkg/routing/ directory (router_*.go files). The routing module contains OS-specific implementations that may interact with system network configurations (router_linux.go, router_windows.go, router_bsd.go). These could have hardcoded paths to system files that may be exploitable or fail on modified systems. Fix: Review all hardcoded system paths. Use APIs instead of direct file access where possible. Validate all file paths before access and handle permission errors gracefully.
• Medium · External Process Execution (nmap) Without Validation — pkg/runner/nmap.go. The codebase includes nmap integration (pkg/runner/nmap.go). Executing external processes like nmap with user-supplied input without proper validation could lead to command injection attacks. Fix: Implement strict input validation and sanitization for all arguments passed to nmap. Use allowlists for port ranges and target specifications. Avoid shell execution; use direct process invocation with argument arrays.
• Medium · Insecure DNS Resolution Fallback — go.mod (retryabledns dependency). The codebase uses github.com/projectdiscovery/retryabledns (v1.0.114) which may have insecure fallback mechanisms. Combined with miekg/dns (v1.1.62), there could be DNS spoofing or poisoning vulnerabilities if retries don't verify responses. Fix: Review DNS resolution logic for DNSSEC validation. Ensure DNS responses are authenticated. Update to latest versions of DNS libraries. Consider implementing DNSSEC verification.
• Medium · SOCKS5 Proxy Without Authentication Validation — go.mod (armon/go-socks5 dependency). The dependency on github.com/armon/go-socks5 (v0.0.0-20160902184237-e75332964ef5) is unmaintained (last update 2016). SOCKS5 support without proper credential handling could allow unauthorized proxy use or man-in-the-middle attacks. Fix: Update or replace the outdated SOCKS5 library with actively maintained alternatives. Implement mandatory SOCKS5 authentication (username/password or certificate-based). Validate proxy credentials before use.
• Medium · Deprecated/Unmaintained Dependencies — go.mod (multiple dependencies). Several dependencies appear outdated or unmaintained: github.com/logrusorgru/aurora (v2.0.3+incompatible), github.com/armon/go-socks5 (2016), and custom forks like Mzack9999/gcache and Mzack9999/gopacket may not receive security updates. Fix: Audit all dependencies for known CVEs using 'go list -json -m all | nancy sleuth'. Replace unmaintained libraries. Establish a dependency update schedule. Monitor security advisories.
• Low · Missing Security Headers Documentation — Repository root. No security policy documentation (SECURITY.md) or vulnerability disclosure guidelines found in the repository structure. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/projectdiscovery/naabu shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live projectdiscovery/naabu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/projectdiscovery/naabu.

What it runs against: a local clone of projectdiscovery/naabu — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in projectdiscovery/naabu | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of projectdiscovery/naabu. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/projectdiscovery/naabu.git
#   cd naabu
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of projectdiscovery/naabu and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "projectdiscovery/naabu(\\.git)?\\b" \\
  && ok "origin remote is projectdiscovery/naabu" \\
  || miss "origin remote is not projectdiscovery/naabu (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "cmd/naabu/main.go" \\
  && ok "cmd/naabu/main.go" \\
  || miss "missing critical file: cmd/naabu/main.go"
test -f "pkg/runner/runner.go" \\
  && ok "pkg/runner/runner.go" \\
  || miss "missing critical file: pkg/runner/runner.go"
test -f "pkg/scan/scan.go" \\
  && ok "pkg/scan/scan.go" \\
  || miss "missing critical file: pkg/scan/scan.go"
test -f "pkg/runner/options.go" \\
  && ok "pkg/runner/options.go" \\
  || miss "missing critical file: pkg/runner/options.go"
test -f "pkg/scan/connect.go" \\
  && ok "pkg/scan/connect.go" \\
  || miss "missing critical file: pkg/scan/connect.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/projectdiscovery/naabu"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.