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/bee-san/RustScan 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.

GO — Healthy across the board

• Last commit 1w ago
• 12 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of bee-san/RustScan — 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 bee-san/RustScan | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bee-san/RustScan. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bee-san/RustScan.git
#   cd RustScan
#
# 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 bee-san/RustScan and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
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/bee-san/RustScan"
  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).

RustScan is a high-performance port scanner written in Rust that finds all 65,535 ports in as little as 3 seconds using adaptive learning algorithms. It automatically pipes discovered ports into Nmap for detailed service enumeration, and includes a built-in scripting engine supporting Python, Lua, and Shell scripts for automated post-scan actions. Monolithic Rust binary structure: src/main.rs is the entry point, src/ contains the core scanning logic, benches/benchmark_portscan.rs provides performance validation, and fixtures/ contains integration test data (hosts.txt, test scripts in .rustscan_scripts/). Build configuration managed via Cargo.toml with LTO and stripping enabled for release binaries.

Security researchers, penetration testers, and DevOps engineers who need to rapidly identify open ports across networks without the speed penalties of traditional scanners like Nmap, while maintaining extensibility through custom scripting.

Production-ready and actively maintained. Version 2.4.1 with organized CI/CD via GitHub Actions (test.yml, build.yml), Dependabot integration, and release automation. The Rust-first codebase (108,993 lines) and comprehensive test coverage suggest active development, though commit recency in the provided data isn't shown.

Moderate risk. The project has a lean dependency tree (clap, async-std, futures for async I/O) but depends on system-level features (rlimit for file descriptor handling). Single author listed (Autumn) creates maintainer concentration risk. The GPL-3.0 license may restrict commercial use without careful licensing review.

Active maintenance evident from Dependabot configuration, release-drafter.yml automation, and performance monitoring via criterion benchmarks (benches/). GitHub Actions CI ensures tests pass on each commit. The adaptive learning algorithm and scripting engine are core focus areas based on README emphasis.

git clone https://github.com/bee-san/RustScan.git
cd RustScan
cargo build --release
./target/release/rustscan --help

Or install pre-built via: brew install rustscan (macOS) or pacman -S rustscan (Arch).

Daily commands:

cargo run -- -r 1-65535 <target_ip>

Or run benchmarks: cargo bench --bench benchmark_portscan. Release binary: cargo build --release && ./target/release/rustscan -h.

• src/main.rs: Entry point and primary CLI handler using clap derive macros for argument parsing
• Cargo.toml: Dependency manifest and build configuration; defines release profile with LTO, panic=abort, and stripping
• benches/benchmark_portscan.rs: Performance regression test suite using criterion; validates speed guarantees mentioned in README
• fixtures/.rustscan_scripts.toml: Configuration pattern for scripting engine integration; demonstrates Python/Perl/Shell script execution
• .github/workflows/test.yml: CI test pipeline; shows how the project validates performance and functionality across commits
• build.rs: Build script that may handle platform-specific compilation or code generation

Core scanning logic: likely in src/ (not fully visible, but main.rs is entry). Add CLI flags: modify argument parsing in src/main.rs via clap derive macros. Add scripting features: extend fixtures/.rustscan_scripts/ pattern and modify the script handler in core logic. Add tests: follow parameterized test pattern in dev-dependencies. Performance regressions: use criterion via cargo bench.

File descriptor limits are critical: rlimit crate is used to maximize ulimit -n, required for scanning many ports concurrently. Nmap must be installed separately if piping results; no validation in code visible. TOML configuration parsing via toml crate is strict; malformed .rustscan_scripts.toml will fail silently. Adaptive learning algorithm depends on previous scan history (likely stored in ~/.config/rustscan or similar, see dirs crate usage), so fresh installs don't benefit from adaptation.

• Adaptive Learning (GCD-based timing optimization) — RustScan's key differentiator over static scanners; the gcd crate is used to mathematically optimize scan timing based on observed response patterns, requiring understanding of this algorithmic approach
• CIDR notation and range expansion — Core to target specification; cidr-utils crate handles IPv4/IPv6 CIDR parsing and expansion (e.g., 192.168.1.0/24), essential for batch scanning workflows
• Async/await and concurrent I/O — RustScan's speed comes from async-std and futures for concurrent port probing; understanding async runtime behavior is critical for modifying scan logic
• File descriptor limits (rlimit) — The rlimit crate allows RustScan to maximize system ulimit -n; scanning thousands of ports concurrently requires careful FD management or scans will silently fail
• DNS-over-TLS (DoT) resolution — hickory-resolver is configured with 'dns-over-rustls' feature; understanding encrypted DNS queries is relevant for network-restricted environments or privacy-focused scanning
• Criterion benchmarking and performance regression testing — RustScan uses criterion for automated performance validation (see benches/); the CI/CD explicitly fails if speed degrades, requiring knowledge of this testing approach when optimizing code
• TOML configuration serialization/deserialization — The toml + serde crates handle .rustscan_scripts.toml and config.toml parsing; understanding serde derive macros is essential for adding configuration options

• nmap/nmap — The canonical port scanner that RustScan pipes results into; understanding nmap's NSE scripting helps contextualize RustScan's scripting engine design
• praetorian-inc/nosqlmap — Similar security tool ecosystem; demonstrates patterns for integrating external tools and building automation around them
• shadowsocks/shadowsocks-rust — Production Rust networking project with similar async-std + futures patterns and cross-platform concerns (macOS/Linux/Windows support)
• tokio-rs/tokio — Alternative async runtime (RustScan uses async-std; Tokio is the competing ecosystem choice with more industry adoption)

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 integration tests for RustScan scripting engine (Python, Lua, Shell)

The repo has fixtures for testing scripts (fixtures/.rustscan_scripts/ with test_script.py, test_script.sh, test_script.pl) and a config file (fixtures/test_rustscan_scripts.toml), but there are no visible integration tests in src/ or tests/ directories. This is critical for a tool that advertises 'Python, Lua, Shell supported' scripting. Adding comprehensive tests would catch regressions in script execution, argument passing, and output handling.

• [ ] Create tests/integration_scripting.rs to test Python/Lua/Shell script execution
• [ ] Add tests for script argument substitution using text_placeholder dependency
• [ ] Test error handling for invalid script headers (fixture: fixtures/.rustscan_scripts/test_script_invalid_headers.txt exists)
• [ ] Verify script output capture and integration with scan results
• [ ] Test against fixtures/test_rustscan_scripts.toml configuration

Add unit tests for address parsing and CIDR handling (src/address.rs)

The codebase uses cidr-utils (0.6.2) and has src/address.rs for address handling, but there are no visible dedicated unit tests for CIDR notation parsing, IP range validation, or edge cases. Given that input validation is critical for a scanner, this is a high-impact area. The fixtures/naughty_strings.txt and fixtures/hosts.txt suggest there's test data available.

• [ ] Add unit tests to src/address.rs covering valid CIDR ranges (e.g., 192.168.0.0/24)
• [ ] Test edge cases: /0, /32 for IPv4, IPv6 ranges, invalid formats
• [ ] Test hosts.txt and naughty_strings.txt against the address parser
• [ ] Verify integration with cidr-utils for range expansion
• [ ] Test error messages for malformed input

Add benchmarks and regression tests for port scanning performance (benches/benchmark_portscan.rs expansion)

The repo advertises '3 seconds at its fastest' and has benches/benchmark_portscan.rs with criterion setup, but the benchmark appears minimal. The port_strategy/range_iterator.rs suggests optimization opportunities. Adding comprehensive benchmarks for different port ranges, scanning strategies, and async task handling would help catch performance regressions and validate the speed claims.

• [ ] Expand benches/benchmark_portscan.rs with benchmarks for different port ranges (10 ports, 100 ports, 1000 ports, all 65535)
• [ ] Add benchmarks for src/port_strategy/range_iterator.rs with various strategies
• [ ] Benchmark async-std task spawning performance with different concurrency levels
• [ ] Add criterion HTML report generation to CI (already configured in Cargo.toml)
• [ ] Create performance regression baseline in .github/workflows/test.yml or build.yml

• Add structured logging output format (JSON/JSONL) for integration with SIEM systems. Currently only colored text output. Modify src/main.rs to conditionally format log output based on --output-format flag.
• Write integration tests for each script type in fixtures/.rustscan_scripts/ (test_script.py, test_script.sh, test_script.pl). Currently only fixture files exist without test assertions; add to test suite validating script execution and error handling.
• Document the adaptive learning algorithm in a separate .md file (e.g., docs/adaptive-learning.md). The README claims it uses 'basic maths' but no implementation details are visible; extract algorithm from src/ and explain GCD-based optimization.

RustScan demonstrates reasonable security practices as a Rust-based tool with modern dependency management and automated CI/CD workflows. However, the application's scripting engine presents code injection risks that require careful input validation. Dependency management could be improved through regular auditing and update practices. The GPL-3.0 license creates legal considerations for users. The project would benefit from a formal security policy and enhanced build hardening measures. Overall security posture is moderate with typical risks for security tools that execute external processes.

• Medium · Outdated or Potentially Vulnerable Dependencies — Cargo.toml - [dependencies] section. Several dependencies use older versions that may contain known vulnerabilities. Notable: anstream pinned to exact version '=1.0.0' which can prevent security updates, and multiple dependencies not using caret/tilde constraints for patch updates. Fix: Run 'cargo audit' regularly to identify vulnerable dependencies. Update dependencies to latest versions and use appropriate version constraints (e.g., '^1.0' instead of exact versions). Enable automated dependency scanning via Dependabot.
• Medium · Insecure Script Execution via Scripting Engine — src/scripts/mod.rs and fixtures/.rustscan_scripts/. The application supports executing external scripts (Python, Lua, Shell) through its scripting engine as evidenced by fixtures containing test scripts. This creates a potential code injection risk if user input is not properly sanitized before script execution. Fix: Implement strict input validation and sanitization before passing any user-controlled data to scripts. Use sandboxing or restricted execution environments for script execution. Avoid using shell=True or equivalent unrestricted execution modes.
• Medium · GPL-3.0 License Compliance Risk — Cargo.toml - license field and LICENSE file. The project uses GPL-3.0-only license which requires source code disclosure and may create legal implications for proprietary derivative works. Fix: Ensure all dependencies are GPL-compatible. Document license obligations clearly. Consider using LGPL or MIT if broader compatibility is needed. Maintain clear attribution and source availability.
• Low · Debug Information in Release Build — Cargo.toml - [profile.release] section. While LTO and stripping are enabled in release profile, the build configuration could be hardened further with additional security flags. Fix: Add additional hardening flags: overflow-checks = true, debug-assertions = false. Consider using RUSTFLAGS with -C overflow-checks=on and other security-relevant compiler flags.
• Low · Potential TOML Configuration File Injection — src/scripts/mod.rs (implied by fixtures) and Cargo.toml. Application reads TOML configuration files (.rustscan_scripts.toml, config.toml) which could be modified by users with file system access. Fix: Validate all TOML configuration file contents strictly. Implement file permission checks. Consider restricting configuration loading from user-writable directories. Use schema validation for configuration files.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md file found in repository for reporting security vulnerabilities responsibly. Fix: Create a SECURITY.md file with clear instructions for reporting vulnerabilities, expected response times, and preferred communication channels (e.g., security@domain.com). Consider enabling GitHub security advisories.

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

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

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