feat: improve CLI, CI, and packaging

- Updated README and documentation, moving and cleaning
- Added bash and CLI completion scripts
- Implemented JSON output for the CLI
- Enabled default sandbox usage, refined landlock message handling
- Integrated `vcpkg` for dependency downloads
- Added utilities for port scanning and tool scanning
- Updated build scripts: added CPack packaging, Fedora RPM build, and CI configurations
- Made numerous bug fixes and clean‑ups across the codebase.

GitOrigin-RevId: c75502466c03a5af29d55ddc88311642d0e59b0d

Author: richyo-codes

.github/workflows/ci.yml

@@ -21,6 +21,12 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y cmake ninja-build build-essential pkg-config clang
 
+      - name: Ensure vcpkg downloads directory
+        run: |
+          VCPKG_DOWNLOADS="${VCPKG_DOWNLOADS:-/tmp/vcpkg-downloads}"
+          mkdir -p "${VCPKG_DOWNLOADS}"
+          echo "VCPKG_DOWNLOADS=${VCPKG_DOWNLOADS}" >> "${GITHUB_ENV}"
+
       - name: Setup vcpkg
         uses: lukka/run-vcpkg@v11
         with:
@@ -40,3 +46,37 @@ jobs:
 
       # - name: Test
       #   run: ctest --test-dir build --output-on-failure
+
+  build-rpm:
+    runs-on: ubuntu-latest
+    container:
+      image: fedora:43
+    steps:
+      - name: Install build dependencies
+        run: |
+          dnf install -y \
+            gcc-c++ cmake ninja-build pkgconf-pkg-config \
+            boost-devel cli11-devel catch2-devel \
+            rpm-build git
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure
+        run: >
+          cmake -S . -B build
+          -DCMAKE_BUILD_TYPE=Release
+          -DPULSECAN_USE_VCPKG=OFF
+          -DBUILD_TESTING=OFF
+
+      - name: Build
+        run: cmake --build build --config Release
+
+      - name: Package (RPM)
+        run: cpack --config build/CPackConfig.cmake -G RPM
+
+      - name: Upload RPM
+        uses: actions/upload-artifact@v4
+        with:
+          name: pulsescan-cpp-rpm
+          path: build/*.rpm

CMakeLists.txt

@@ -1,16 +1,21 @@
 cmake_minimum_required(VERSION 3.20)
 
-message("VCPKG_ROOT: $ENV{VCPKG_ROOT}")
-message("CMAKE_TOOLCHAIN_FILE: $ENV{CMAKE_TOOLCHAIN_FILE}")
+option(PULSECAN_USE_VCPKG "Use vcpkg toolchain when available" ON)
 
-list(APPEND CMAKE_PROJECT_TOP_LEVEL_INCLUDES "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake")
-list(APPEND CMAKE_TRY_COMPILE_PLATFORM_VARIABLES CMAKE_PROJECT_TOP_LEVEL_INCLUDES)
+if(PULSECAN_USE_VCPKG)
+  message("VCPKG_ROOT: $ENV{VCPKG_ROOT}")
+  message("CMAKE_TOOLCHAIN_FILE: $ENV{CMAKE_TOOLCHAIN_FILE}")
+  if(DEFINED ENV{VCPKG_ROOT} AND EXISTS "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake")
+    list(APPEND CMAKE_PROJECT_TOP_LEVEL_INCLUDES "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake")
+    list(APPEND CMAKE_TRY_COMPILE_PLATFORM_VARIABLES CMAKE_PROJECT_TOP_LEVEL_INCLUDES)
+  endif()
+endif()
 
 if(POLICY CMP0167)
   cmake_policy(SET CMP0167 NEW)
 endif()
 
-project(pulsescan_cpp LANGUAGES CXX)
+project(pulsescan_cpp VERSION 1.0.0 LANGUAGES CXX)
 
 option(ENABLE_STACKTRACE "Enable Boost stacktrace logging" OFF)
 option(ENABLE_ASIO_SSL "Enable Boost.Asio SSL support" OFF)
@@ -21,7 +26,7 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 find_package(CLI11 CONFIG REQUIRED)
-find_package(Boost REQUIRED COMPONENTS asio)
+find_package(Boost REQUIRED COMPONENTS asio system)
 if(ENABLE_STACKTRACE)
   find_package(Boost REQUIRED COMPONENTS stacktrace_basic)
 endif()
@@ -34,6 +39,7 @@ add_executable(pulsescan_cpp
     src/core/logging.cpp
     src/core/output.cpp
     src/core/ping_loop.cpp
+    src/core/ports.cpp
     src/core/status.cpp
     src/net/icmp_packet.cpp
     src/core/resolve.cpp
@@ -57,7 +63,7 @@ else()
 endif()
 target_include_directories(pulsescan_cpp PRIVATE src)
 
-target_link_libraries(pulsescan_cpp PRIVATE Boost::asio CLI11::CLI11)
+target_link_libraries(pulsescan_cpp PRIVATE Boost::asio Boost::system CLI11::CLI11)
 if(ENABLE_STACKTRACE)
   target_link_libraries(pulsescan_cpp PRIVATE Boost::stacktrace_basic)
   target_compile_definitions(pulsescan_cpp PRIVATE ENABLE_STACKTRACE)
@@ -78,13 +84,14 @@ if(BUILD_TESTING)
       src/core/cli.cpp
       src/core/logging.cpp
       src/core/output.cpp
+      src/core/ports.cpp
       src/core/resolve.cpp
       src/core/status.cpp
       src/net/icmp_packet.cpp
       src/net/udp_probes.cpp
   )
   target_include_directories(pulsescan_cpp_tests PRIVATE src)
-  target_link_libraries(pulsescan_cpp_tests PRIVATE Boost::asio CLI11::CLI11 Catch2::Catch2WithMain)
+  target_link_libraries(pulsescan_cpp_tests PRIVATE Boost::asio Boost::system CLI11::CLI11 Catch2::Catch2WithMain)
   if(ENABLE_STACKTRACE)
     target_link_libraries(pulsescan_cpp_tests PRIVATE Boost::stacktrace_basic)
     target_compile_definitions(pulsescan_cpp_tests PRIVATE ENABLE_STACKTRACE)
@@ -94,3 +101,22 @@ if(BUILD_TESTING)
   endif()
   catch_discover_tests(pulsescan_cpp_tests)
 endif()
+
+include(GNUInstallDirs)
+install(TARGETS pulsescan_cpp RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(FILES README.md LICENSE
+        DESTINATION ${CMAKE_INSTALL_DOCDIR})
+install(DIRECTORY docs/
+        DESTINATION ${CMAKE_INSTALL_DOCDIR})
+install(FILES scripts/completions/pulsescan-cpp.bash
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/bash-completion/completions
+        RENAME pulsescan-cpp)
+
+set(CPACK_PACKAGE_NAME "pulsescan-cpp")
+set(CPACK_PACKAGE_VENDOR "ryoung")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "PulseScan C++ async port and host scanner")
+set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
+set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+set(CPACK_RPM_PACKAGE_AUTOREQPROV ON)
+set(CPACK_GENERATOR "DEB;RPM")
+include(CPack)

README.md

@@ -25,39 +25,40 @@ cmake --build build
 
 Basic scan (replace with hosts you are authorized to test):
 ```bash
-./build/pulsescan-cpp localhost -p 80,443,8000-8005 -t 1.5 --max-inflight 500
+./pulsescan-cpp localhost -p 80,443,8000-8005 -t 1.5 --max-inflight 500
 ```
 
 Multi-host scan:
 ```bash
-./build/pulsescan-cpp localhost 127.0.0.1 ::1 -p 22,80
+./pulsescan-cpp localhost 127.0.0.1 ::1 -p 22,80
 ```
 
 Ping mode (repeat and report changes):
 ```bash
-./build/pulsescan-cpp localhost -p 80 --ping --interval 2
+./pulsescan-cpp localhost -p 80 --ping --interval 2
 ```
 
 ICMP ping (requires root or CAP_NET_RAW):
 ```bash
-sudo ./build/pulsescan-cpp 127.0.0.1 --icmp-ping -c 3
+sudo ./pulsescan-cpp 127.0.0.1 --icmp-ping -c 3
 ```
 
 Modes:
 - `-m connect` (default): TCP connect scan.
 - `-m banner`: TCP connect plus a short banner read (`--banner-timeout`, `--banner-bytes`).
-- `-m udp`: UDP probe that sends a protocol-specific payload when known (DNS, NTP, QUIC VN, SIP, IAX2), otherwise a minimal payload. No reply is reported as `open|filtered`.
+- `-m udp`: UDP probe that sends a protocol-specific payload when known (DNS, NTP, SIP), otherwise a minimal payload. No reply is reported as `open|filtered`.
 
 Features:
 - Multi-host scanning.
 - `--ping` change detection.
 - ICMP ping mode with CIDR/range expansion.
 - IPv4/IPv6 filtering (`-4`/`-6`).
 - Optional reverse DNS (`--reverse-dns`).
-- Optional sandboxing (`--sandbox`) using Landlock (Linux) or Capsicum (FreeBSD).
+- Report-style text output by default, JSON line output (`--output json`) when needed.
+- Sandboxing enabled by default using Landlock (Linux) or Capsicum (FreeBSD).
 - Press Enter (or SIGINFO on FreeBSD) to print progress while running.
 
 ## Notes / Next steps
 - UDP scans are best-effort; no response is reported as `open|filtered`.
 - ICMP ping requires root or `CAP_NET_RAW`.
-- Consider JSON output and per-host/port rate caps for larger sweeps.
+- Consider per-host/port rate caps for larger sweeps.

build.md

@@ -4,7 +4,10 @@ set(CMAKE_SYSTEM_PROCESSOR x86_64)
 
 set(FREEBSD_TARGET "x86_64-unknown-freebsd14.3")
 
-if(NOT DEFINED FREEBSD_SYSROOT)
+if(NOT DEFINED FREEBSD_SYSROOT OR FREEBSD_SYSROOT STREQUAL "")
+  set(FREEBSD_SYSROOT "$ENV{FREEBSD_SYSROOT}")
+endif()
+if(NOT DEFINED FREEBSD_SYSROOT OR FREEBSD_SYSROOT STREQUAL "")
   message(FATAL_ERROR "FREEBSD_SYSROOT is not set (path to FreeBSD base sysroot).")
 endif()
 

cmake/toolchains/freebsd14.cmake

@@ -0,0 +1,75 @@
+# Benchmarking PulseScan vs Nmap
+
+This document outlines a simple, repeatable way to compare PulseScan's range
+scanning performance against nmap. The goal is a fair wall-clock comparison
+with minimal DNS or network noise.
+
+## General guidance
+
+- Use a stable test range you own (lab VLAN, VM subnet, loopback).
+- Disable DNS lookups (PulseScan: no `--reverse-dns`, nmap: `-n`).
+- Keep scan scope identical (same hosts, same ports, same protocol).
+- Use multiple runs and a warm-up to reduce variance.
+- Do not scan public networks or hosts without permission.
+
+## Tooling
+
+`hyperfine` is a good fit for measuring total runtime.
+
+Install (example for Debian/Ubuntu):
+
+```bash
+sudo apt-get install -y hyperfine
+```
+
+## Suggested baselines
+
+Pick a range and port set:
+
+- Range: `192.168.1.0/24` (example)
+- Ports: 10 common ports
+- Timeouts: 1.0s
+- No DNS, no banner, no UDP (TCP connect only)
+
+## Example: TCP connect scan
+
+PulseScan:
+
+```bash
+./build/pulsescan-cpp 192.168.1.0/24 \
+  --top-ports 10 \
+  -t 1.0 \
+  --max-inflight 200 \
+  --output json > /dev/null
+```
+
+nmap:
+
+```bash
+nmap -n -Pn \
+  --max-retries 1 \
+  --host-timeout 1s \
+  -p 20,21,22,23,25,53,80,81,88,110 \
+  192.168.1.0/24 > /dev/null
+```
+
+Hyperfine:
+
+```bash
+hyperfine --warmup 1 --runs 5 \
+  './build/pulsescan-cpp 192.168.1.0/24 --top-ports 10 -t 1.0 --max-inflight 200 --output json > /dev/null' \
+  'nmap -n -Pn --max-retries 1 --host-timeout 1s -p 20,21,22,23,25,53,80,81,88,110 192.168.1.0/24 > /dev/null'
+```
+
+## Notes on fairness
+
+- `--max-inflight` is PulseScan's concurrency knob; nmap has its own timing engine.
+  You can also try `-T3` or `-T4` in nmap to explore different profiles.
+- `--host-timeout` in nmap is a hard cap per host; adjust to match PulseScan timeouts.
+- If you use `--ping` or `--icmp-ping`, benchmark them separately.
+
+## Interpreting results
+
+Hyperfine reports mean/median runtime and standard deviation. Compare relative
+performance on the same hardware and network conditions. If results are noisy,
+increase run count or narrow the test range.

docs/benchmark.md

@@ -0,0 +1,54 @@
+# Build
+
+## Configure and Build
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+```
+
+## Dependency Source (system vs vcpkg)
+
+By default, the build uses vcpkg if `VCPKG_ROOT` is set. To prefer system
+packages, disable vcpkg:
+
+```bash
+cmake -S . -B build -DPULSECAN_USE_VCPKG=OFF
+```
+
+To force vcpkg (static libs) when it is available:
+
+```bash
+cmake -S . -B build -DPULSECAN_USE_VCPKG=ON
+```
+
+## Packaging (DEB/RPM)
+
+Packages are generated via CPack. After a successful build, run:
+
+```bash
+cpack --config build/CPackConfig.cmake -G DEB
+cpack --config build/CPackConfig.cmake -G RPM
+```
+
+Or use the package target:
+
+```bash
+cmake --build build --target package
+```
+
+## Enable Stacktrace (Optional)
+
+The stacktrace support is optional and off by default.
+
+Enable the vcpkg feature:
+
+```bash
+vcpkg install --feature-flags=manifest pulsescan-cpp[stacktrace]
+```
+
+Enable the CMake toggle:
+
+```bash
+cmake -S . -B build -DENABLE_STACKTRACE=ON
+```