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/angryip/ipscan 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.

WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 4 active contributors
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ GPL-2.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 angryip/ipscan repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/angryip/ipscan.

What it runs against: a local clone of angryip/ipscan — 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 angryip/ipscan | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 188 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.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"

# 4. Critical files exist
test -f "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f "src/net/azib/ipscan/fetchers" \\
  && ok "src/net/azib/ipscan/fetchers" \\
  || miss "missing critical file: src/net/azib/ipscan/fetchers"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "gradle.properties" \\
  && ok "gradle.properties" \\
  || miss "missing critical file: gradle.properties"

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

Angry IP Scanner is a fast, cross-platform network discovery tool written in Java that identifies active hosts, open ports, and device information across local and remote networks. It provides a native GUI using Eclipse SWT, runs on Linux/Windows/macOS, and uses modular Fetcher classes to gather MAC addresses, hostnames, ports, and custom network data without requiring administrative privileges for basic operations. Monolithic Java project with src/net/azib/ipscan/fetchers containing pluggable Fetcher classes for each data source type (MAC, hostname, port, etc.), config/logging.properties for runtime configuration, and ext/ containing platform-specific bundles (deb-bundle, mac-bundle with Info.plist templates, and NSIS installer config via ext/jna.pro). Tests live in test/ and CI builds for linux64, win64, macX86, macArm64 via Gradle configurations.

Network administrators, IT support staff, and security professionals who need to quickly map network topology and identify active devices; also developers contributing native OS-specific fixes (especially macOS users) who can reproduce network-related issues in their environment.

Production-ready and actively maintained. The project has CI/CD via GitHub Actions (build.yml), uses semantic versioning (git describe --tags), targets Java 17+, and includes NSIS installers for Windows and Debian/RPM package support. Code is GPL v2 licensed and has been actively developed with pull requests encouraged from the community.

Low risk for stability but platform-specific fragility: SWT native components vary by OS, and the codebase explicitly notes 'millions of different networks, configurations and devices' make testing difficult. Single maintainer risk is mitigated by PR-driven contributions, but breaking changes in Java 17+ modules or SWT versions could impact builds. macOS support historically lags behind other platforms.

Active development with GitHub Actions CI validating builds across platforms. The codebase is at version managed via git tags (no fixed version visible in snippets). The Makefile and build.gradle suggest ongoing support for native image compilation (build-native-image.sh exists) and multi-platform distribution. No specific recent milestone mentioned in provided data, but PR-based workflow is actively encouraged.

git clone https://github.com/angryip/ipscan.git && cd ipscan && ./gradlew current (or make for available targets) to build for your platform. For development, open the cloned project in IntelliJ IDEA Community Edition and use the pre-configured run configurations in .idea/runConfigurations/Main.xml to launch in Debug mode.

Daily commands: ./gradlew current (builds for your current OS) or ./gradlew all (requires Ubuntu with openjdk-21-jdk, rpm, fakeroot). Run with java -jar build/libs/<jar-file>.jar. Pre-configured IntelliJ run configs available: use Main.xml for GUI or Unit_tests.xml for tests.

• build.gradle — Gradle build configuration defining dependencies (SWT, ProGuard), platform detection, and build targets for Linux/Windows/macOS—essential for understanding the entire build pipeline and artifact generation
• src/net/azib/ipscan/fetchers — Core fetcher architecture where network scanning logic is implemented; contributors must understand this to add new scanning capabilities or fix platform-specific issues
• .github/workflows/build.yml — CI/CD pipeline defining automated builds and tests across platforms—critical for understanding release process and platform-specific build requirements
• README.md — Project overview, build instructions, and contribution guidelines; establishes the SWT-based GUI architecture and cross-platform scope
• gradle.properties — Gradle configuration properties defining version, platform-specific JVM arguments, and dependency versions used across all builds
• ext/win-installer/Installer/Installer.nsi — Windows installer configuration using NSIS; required for understanding Windows-specific packaging and distribution setup
• ext/mac-bundle/Angry IP Scanner.app/Contents/Info.plist — macOS app metadata and configuration; essential for understanding macOS-specific packaging and distribution requirements

• SWT GUI Layer (SWT, platform-native components) — Renders native UI, captures user input (IP range, scan options), displays results table, and manages user interactions
  • Failure mode: GUI fails to render on unsupported platform variant; native API mismatch causes crashes or visual artifacts
• Scanner Engine (Java concurrency, thread pools) — Orchestrates multi-threaded fetcher execution, manages IP iteration, aggregates results, and coordinates cancellation
  • Failure mode: Thread leaks on cancel; deadlocks in result aggregation; resource exhaustion under high concurrency

Add a New Network Fetcher (Scanner Capability)

1. Create a new fetcher class extending AbstractFetcher in src/net/azib/ipscan/fetchers/ directory, implementing the required scanning logic for a specific service (port, protocol, or metadata) (src/net/azib/ipscan/fetchers)
2. Register the fetcher in the fetcher registry/factory configuration to make it available in the UI scanner (src/net/azib/ipscan/fetchers)
3. Add unit tests in the corresponding test directory to verify the fetcher works across Linux, Windows, and macOS platforms (src/test)
4. Update CHANGELOG with the new fetcher capability (CHANGELOG)

Add a New GUI Component or Settings Panel

1. Create a new SWT Composite class in src/net/azib/ipscan/gui/ implementing the UI panel with native components compatible across platforms (src/net/azib/ipscan/gui)
2. Add required icons as SVG and 2x PNG variants in resources/images/ for button and menu icons (resources/images)
3. Register the new component in the main application GUI initialization or preferences system (src/net/azib/ipscan/gui)
4. Test on all three platforms (Linux, Windows, macOS) using IntelliJ debug configuration (.idea/runConfigurations/Main.xml)

Support a New Platform or Modify Build Output

1. Update build.gradle platform detection logic to recognize the new platform and add platform-specific dependencies via gradle.properties (build.gradle)
2. Create platform-specific installer configuration in ext/ (e.g., ext/rpm-bundle/ for RPM or similar NSIS variant) (ext)
3. Add platform-specific run configuration and build target to the Makefile or update gradlew tasks (Makefile)
4. Update .github/workflows/build.yml to include the new platform in the CI/CD matrix (.github/workflows/build.yml)

• SWT (Standard Widget Toolkit) — Provides native GUI components for Linux, Windows, and macOS from a single Java codebase; eliminates platform abstraction overhead compared to Swing
• Gradle — Enables platform-specific build variants, JVM argument configuration per OS, and seamless multi-platform artifact generation
• ProGuard — Obfuscates and optimizes bytecode; reduces JAR size and provides intellectual property protection for the scanning logic
• GraalVM Native Image — Compiles Java to standalone native binaries; eliminates JVM dependency, improves startup time, and simplifies user installation
• Platform-specific installers (NSIS, .deb, .app) — Delivers native installation experience on each OS; integrates with system package managers and ensures proper file permissions

• SWT over JavaFX or Swing

  • Why: Need for native platform UI components and deep OS integration; SWT provides true native look-and-feel without overhead
  • Consequence: Tighter OS coupling; requires platform-specific SWT binaries in build; GUI code must account for SWT differences across platforms

• Multi-threaded fetcher architecture

  • Why: Network scanning must be responsive and handle hundreds of concurrent IP addresses efficiently
  • Consequence: Increased complexity in thread synchronization, result aggregation, and cancellation handling; potential race conditions in shared state

• Pluggable fetcher pattern

  • Why: Enable extensibility for new scanning capabilities without modifying core engine
  • Consequence: Architectural abstraction overhead; fetcher registry management and dependency injection required

• Cross-platform single codebase

  • Why: Reduce maintenance burden and ensure feature parity across Linux, Windows, and macOS
  • Consequence: Platform-specific code paths and testing overhead; difficult edge cases require contributor environments for each OS

• Real-time distributed scanning across multiple machines (single-machine tool)
• Authentication or credential management for advanced network access
• Packet capture or deep packet inspection (uses higher-level network APIs)
• Web-based or headless API interface (desktop GUI application only)
• Autonomous threat detection or machine learning-based analysis

Java module restrictions require explicit exports via javaModules configuration (java.base, java.prefs, java.logging, jdk.crypto.ec); missing these causes reflection failures in SWT. SWT native components vary significantly by platform — same code may behave differently on Linux GTK vs Windows native vs macOS Cocoa. Platform detection in build.gradle uses System.getProperty() so cross-compilation is not possible (must build on target OS). Windows/deb/rpm builds require the host OS or specific tools (NSIS on Windows, fakeroot/rpm on Linux). git describe --tags is used for versioning, so ensure git history is available when building.

• SWT (Standard Widget Toolkit) Native Components — Angry IP Scanner uses SWT to provide platform-native GUI controls that differ significantly across Linux (GTK), Windows (Win32), and macOS (Cocoa); understanding these differences is essential for debugging cross-platform GUI bugs and why macOS often lags in support
• Pluggable Fetcher Architecture — The core extensibility pattern in Angry IP Scanner where each Fetcher subclass independently gathers one type of network data (MAC, hostname, port, etc.), allowing new data sources to be added without modifying the scanner core
• Platform-Specific Binary Packaging — Angry IP Scanner manages four distinct packaging targets (Debian/RPM for Linux, NSIS installer for Windows, app bundle for macOS) with platform-specific native launchers; understanding this complexity explains why cross-platform testing is difficult
• Java Module System (Java 9+) — Angry IP Scanner explicitly declares required Java modules (java.base, java.prefs, java.logging, jdk.crypto.ec) in build.gradle; misconfiguring these causes reflection failures in native code and SWT
• Network Host Discovery (ARP/ICMP/Port Scanning) — Angry IP Scanner combines multiple discovery techniques (ARP broadcasts, ICMP ping, TCP/UDP port enumeration) via its Fetcher architecture; understanding which technique works on which network type is critical for diagnosing why hosts appear missing
• ProGuard Code Obfuscation and Optimization — Angry IP Scanner uses ProGuard 7.8.1 in the build pipeline to shrink and obfuscate the JAR; this means debugging production builds requires symbol maps and can mask the original source code structure
• JNA (Java Native Access) — Angry IP Scanner uses JNA to call native OS APIs (especially for network operations that require platform-specific system calls); JNA versions vary by platform configuration, and native method signatures must match the target OS exactly

• nmap/nmap — Industry-standard network scanner that Angry IP Scanner is often compared against; nmap is lower-level CLI-focused while Angry IP Scanner provides GUI convenience
• zmap/zmap — Fast internet-wide scanner emphasizing speed at scale; complementary to Angry IP Scanner's focus on friendly cross-platform local network discovery
• eclipse/swt — The native GUI framework Angry IP Scanner depends on; understanding SWT lifecycle and platform differences is critical for debugging GUI issues
• openjdk/jdk — Angry IP Scanner targets Java 17+ with specific module requirements; JDK version compatibility affects build and runtime behavior, especially for jdk.crypto.ec

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 unit tests for Fetcher implementations in src/net/azib/ipscan/fetchers

The README specifically mentions Fetcher classes as key extension points, but the test directory structure is sparse. Adding comprehensive unit tests for individual Fetcher implementations (port scanners, OS detection, etc.) would improve code reliability and make it easier for contributors to understand how fetchers work and add new ones without breaking existing functionality.

• [ ] Examine existing test files in test/ directory to understand current test patterns
• [ ] Identify 2-3 critical Fetcher classes in src/net/azib/ipscan/fetchers/ that lack test coverage
• [ ] Create test/net/azib/ipscan/fetchers/ directory structure matching source layout
• [ ] Write unit tests for each Fetcher covering success cases, error handling, and edge cases
• [ ] Run tests locally with ./gradlew test to verify they pass on your platform

Create platform-specific CI workflows for macOS and Linux builds in .github/workflows/

The current build.yml workflow likely runs on a single platform, but the codebase explicitly supports Linux, Windows, and macOS with platform-specific SWT dependencies and native bundling (deb, rpm, dmg, nsi installers). Adding separate CI workflows for each platform would catch platform-specific bugs early and ensure native installers build correctly before release.

• [ ] Review existing .github/workflows/build.yml to understand current matrix strategy
• [ ] Create .github/workflows/build-macos.yml with macos-latest runner, testing macOS-specific SWT and creating .app bundle via ext/mac-bundle/
• [ ] Create .github/workflows/build-linux.yml with ubuntu-latest runner, testing linux64 SWT and validating deb/rpm packaging from ext/deb-bundle/ and ext/rpmbuild/
• [ ] Add workflow_dispatch triggers to allow manual testing per-platform
• [ ] Document in README.md how to trigger platform-specific builds and review artifacts

Add integration tests for cross-platform GUI rendering in src/net/azib/ipscan (SWT components)

The project uses SWT for platform-native GUI components, and the README encourages macOS users to submit PRs for platform issues. Adding integration tests that verify SWT UI components render and respond correctly on each platform would reduce regressions and make the codebase more maintainable for contributors testing on different OSes.

• [ ] Review test/ directory structure to identify where GUI/integration tests should live
• [ ] Create test/net/azib/ipscan/gui/ or similar directory for SWT integration tests
• [ ] Write tests that instantiate main UI classes (likely in src/net/azib/ipscan/gui/) and verify key components (tables, buttons, text inputs) exist and respond to events
• [ ] Ensure tests use headless or virtual display modes for CI (xvfb on Linux, xquartz on macOS)
• [ ] Update .github/workflows/ to run GUI tests with display setup on macOS and Linux runners

• Add missing unit tests for src/net/azib/ipscan/fetchers/ — currently no test files visible in test/ directory for individual Fetcher implementations; could start with a simple Fetcher like MAC address or hostname resolution
• Create platform-specific troubleshooting documentation in README or docs/ for macOS-specific SWT issues (the code notes 'especially macOS users' need to submit PRs) — document SWT native component quirks on Apple Silicon (macArm64) vs Intel
• Extend build.gradle to support 32-bit Linux builds cleanly — code has logic for 'linux64' and 'linux32' but only linux64 dependency is visible, likely breaking 32-bit Linux builds

The Angry IP Scanner codebase shows reasonable security practices overall, but has several build-time concerns. The primary risk is unrestricted command execution in the build script using Runtime.exec(), which could be exploited if extended with user input. Platform detection via System properties and version generation from git tags require validation. Dependency management relies on explicit exclusions without clear documentation. The codebase lacks hardcoded secrets or obvious injection vulnerabilities in the visible files, and follows a standard Java project structure. Recommend focusing on hardening the build script, implementing dependency verification, and enforcing the Java 17 toolchain requirement.

• High · ProGuard Gradle Plugin Dependency — build.gradle - buildscript dependencies. The build script includes 'com.guardsquare:proguard-gradle:7.8.1' as a build dependency. While not directly exploitable in the application, using build tools from repositories requires verification of artifact integrity and source legitimacy. ProGuard is a legacy obfuscation tool with limited active maintenance. Fix: Verify ProGuard dependency is necessary. Consider using modern alternatives like R8 (built into Gradle). Implement dependency verification and use gradle lockfiles to pin transitive dependencies.
• High · Unrestricted Command Execution in Build Script — build.gradle - exec() function definition. The custom exec() function in build.gradle executes shell commands via Runtime.getRuntime().exec() with user input from git describe command. While the immediate use case appears safe, this pattern is vulnerable to injection attacks if extended with user-controlled input. The failOnError parameter defaults to true but can be overridden. Fix: Replace Runtime.exec() with ProcessBuilder for better control. Validate and sanitize all command inputs. Use gradle's built-in git integration or plugin instead of raw command execution. Avoid shell interpretation by using array syntax.
• Medium · Excluded SWT Transitive Dependencies — build.gradle - configurations block. The build configuration explicitly excludes 'org.eclipse.swt' via 'all*.exclude module'. While this may be intentional for platform-specific handling, excluding transitive dependencies without clear documentation can lead to unmet dependencies or version conflicts. Fix: Document why SWT exclusion is necessary. Use dependency constraints and BOM (Bill of Materials) for explicit version management. Verify SWT is properly provided at runtime for each platform configuration.
• Medium · Version String Generated from Git Tags — build.gradle - version assignment. The application version is derived from 'git describe --tags' output with fallback to 'unknown'. If this version string is used in comparisons, logging, or serialization without validation, it could be manipulated or cause unexpected behavior. Fix: Validate version string format against semantic versioning regex. Sanitize version before use in comparisons. Consider using buildConfig or manifest entries with version validation logic.
• Medium · Platform Detection via System Properties — build.gradle - platform detection logic. Platform detection relies on System.getProperty() for os.name and os.arch. These values can theoretically be manipulated and are used to determine which native libraries to load, which could impact runtime behavior. Fix: Add validation that platform is one of expected values. Log platform detection results for debugging. Consider supplementary runtime checks in the application to verify loaded native libraries match expected platform.
• Low · Incomplete Dependency Declaration — build.gradle - dependencies block (end of provided snippet). The build.gradle file appears to be truncated at the SWT dependency declaration for Windows 64-bit platform, which may indicate incomplete configuration or hidden dependencies. Fix: Review complete build.gradle to ensure all dependencies are properly declared and versions are pinned. Use 'gradle dependencies' task to verify dependency tree.
• Low · Java Version 17 Requirement Not Enforced — build.gradle - sourceCompatibility assignment. While sourceCompatibility and targetCompatibility are set to 17, there is no gradle wrapper version requirement or build failure mechanism if older JDK is used to compile. Fix: Add 'java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }' for toolchain enforcement. Document Java 17 requirement in README. Add JDK version check in gradle wrapper or build script.

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.