External Tool Dependencies

Overview

PortShim orchestrates established security tooling rather than reimplementing it. The inventory of what gets installed comes from deploy.py; the "used by" column comes from the code that actually invokes each binary. Some tools are installed and configured but run by the AI agent following its skill instructions rather than by any script — those rows are marked Agent.

Tags mark how a tool is driven. A row carrying no tag is invoked directly by PortShim's own code — the core pipeline table is entirely runtime, so none of its rows are tagged, and a table in a section that is itself dedicated to agent-driven tools carries no per-row tag either. The "If missing" column states the real consequence — graded Hard stop / Degrades / No effect where the impact varies, and naming what stops working where a whole module depends on the tool.

Tag	Meaning
Agent	Installed and configured, run by the AI agent per its skill — no code invocation
Optional	Needed for one mode or module only

Core pipeline

Tool	What it is	Why PortShim uses it	If missing
nmap	Port scanner and NSE script host	Host discovery, subnet sweeps, service/version fingerprinting, and the CVE input for Phase 2	Hard stop — there is no substitute
ip (iproute2)	Interface and routing table inspection	Determines local subnets and the default gateway before sweeping	Degrades — subnet discovery degrades; gateways go unidentified
curl	HTTP client	HTTP fingerprinting and target reachability checks	Degrades — HTTP probing is skipped
python3 ≥ 3.10	Runtime	Everything. PEP 668 distros require a virtualenv	Hard stop
git	Version control	Cloning the nmap-vulners NSE script; cloning PortShim itself	Degrades — nmap-vulners install unavailable
masscan	Asynchronous port scanner	Fast host discovery on large ranges — seconds instead of minutes	Degrades — falls back to nmap -sn automatically
go	Go toolchain	Compiling and installing nuclei, httpx and subfinder	Degrades — the Go tools cannot be installed
pip + python3-venv	Python packaging and virtualenv	Installing the Python dependencies into a venv — PEP 668 distros refuse system-level installs	Hard stop — the Python dependencies cannot be installed
nodejs + npm	Node runtime	Installing the Anthropic Cybersecurity Skills layer the agent works from (npx skills add …)	Degrades — the agent skill layer cannot be installed

Optional — rendering only

Installed by deploy.py, but no code path invokes it and no pipeline output depends on it.

Tool	What it is	Used by	If missing
graphviz (dot)	DOT renderer	Not invoked — topology.py --dot emits DOT text; rendering the image is a manual step	No effect — no diagram image; the DOT text output is unchanged

Local LLM

Required for --mode local. Used opportunistically in --mode hybrid, which falls back to the cloud LLM if it is absent.

Tool	What it is	Why PortShim uses it	If missing
llama-server (b9870+)	Local inference server	Local model inference for recon/CVE analysis and exploit reasoning — the air-gapped path	Local mode unavailable; hybrid falls back to the cloud LLM

Model weights are a separate dependency — the three GGUF files under ~/local-models/, or wherever PD_MODELS_DIR points. See the air-gapped operations page.

Wireless assessment

Used by portshim wireless …. An external USB adapter is required — the internal Wi-Fi interface is never used.

Tool	What it is	Why PortShim uses it	If missing
iw	nl80211 interface control	Interface enumeration, capability probing, managed-mode scans, association checks	Wireless module unusable
nmcli	NetworkManager client	Detects NetworkManager interference before capture	Interference detection skipped — captures may fail
airmon-ng	Monitor-mode management	Enables monitor mode	No capture possible
airodump-ng	Passive wireless capture	AP discovery and handshake capture	Scan and capture fail
aireplay-ng	Frame injection	Targeted deauth to force a handshake	Deauth unavailable
aircrack-ng	Wireless protocol cracking	WEP/PSK cracking and capture verification	Cracking unavailable
hcxdumptool	PMKID capture	Capture path that survives PMF-protected networks	PMKID route unavailable
hcxpcapngtool	pcapng → hashcat/john converter	Converts captures into crackable hash files	No cracking input
macchanger	MAC address spoofing	Operator identity hygiene	Adapters retain their real MAC
hashcat	GPU-accelerated cracking	Candidate and wordlist attacks against captured handshakes	Cracking unavailable
john	CPU cracking	Fallback when there is no usable GPU	No GPU-less fallback
hashid	Hash type identification	Identifies the hash format inside a capture before cracking	Hash type auto-detection skipped

Exploit phase

Tool	Role	If missing
searchsploit	Maps verified CVEs to public exploits from the local Exploit-DB	Findings carry no exploit references
hydra	Agent — credential testing during Phase 3	Phase 3 credential checks unavailable
sshpass	Agent — non-interactive SSH work during Phase 3	Interactive prompts block automated SSH

Installed and configured, but agent-driven

These are installed by deploy.py and configured per engagement profile, but no PortShim script invokes them. The AI agent runs them following the site-assessment-pipeline skill, and engagement-profiles.py supplies the per-profile flags.

Tool	What it is	If missing
nuclei	Template-based vulnerability scanner; flags set per stealth profile	Phase 2 relies on nmap-vulners CVE data alone
httpx	HTTP probing to JSON; topology.py --httpx consumes its output	Topology loses HTTP titles and tech-stack data
subfinder	Subdomain enumeration — credited upstream and installed, but no flags configured and no invocation anywhere in the repo	No effect on internal LAN engagements
metasploit	Exploit framework — opt-in via deploy.py --with-msf	Phase 3 verification limited to manual techniques
kismet	Wireless IDS / passive capture — skill reference only	No effect

Not a dependency

tshark and tcpdump are not used anywhere in the codebase. Packet capture for protocol-level exploit verification is an open feature request, tracked as issue #42 on the repository.

Python packages

Package	Import name	Used for
python-docx	docx	Technical report (.docx)
python-pptx	pptx	Executive deck (.pptx)
openpyxl	openpyxl	Remediation checklist and retest diff (.xlsx)
pyyaml	yaml	Knowledge-source manifests
hashid	—	Provides the hashid binary used by the wireless cracker
Pillow, numpy	PIL, numpy	Video pipeline — not installed by deploy.py (gap 1 below)
requests, fpdf2, paramiko	—	Installed, but never imported by any file (gap 4 below)

Package → binary map

Several packages provide the binaries the code invokes.

Package	Provides
aircrack-ng	aircrack-ng, airmon-ng, airodump-ng, aireplay-ng
hcxtools	hcxpcapngtool
hcxdumptool	hcxdumptool
exploitdb	searchsploit
graphviz	dot
iproute2, curl	ip, curl — invoked but not installed by deploy.py (gap 3)

Known gaps

Recorded rather than worked around. None of these block the core pipeline.

1. Pillow and numpy are undeclared. The video scripts import them, but they are in neither deploy.py nor pyproject.toml, so a fresh deploy cannot run the video pipeline.
2. ffmpeg is undeclared. The video scripts invoke it directly; deploy.py does not install it.
3. curl and iproute2 are invoked but not installed. Both are near-universal on Linux desktops, so this is a documentation gap more than a functional one.
4. requests, fpdf2 and paramiko are installed but never imported by any file in the tree.
5. subfinder is documented but unused. It is credited upstream and installed by deploy.py; no script invokes it and no profile configures it.
6. graphviz is installed, but only DOT text is produced. It matters only if you render the diagram yourself.
7. The preflight check covers four tools only — nmap, nuclei, httpx, llama-server. Everything else fails at first use, mid-phase.

Verification

Check what is present on your host:

# Core + tools installed by deploy.py
which nmap ip curl git masscan
which llama-server iw nmcli airmon-ng airodump-ng aireplay-ng aircrack-ng \
      hcxdumptool hcxpcapngtool macchanger hashcat john hashid searchsploit hydra sshpass \
      nuclei httpx subfinder msfconsole kismet

# Python packages actually importable
.venv/bin/python -c "import openpyxl, docx, pptx, yaml, PIL, numpy; print('OK')"
# note: the module is `fpdf`, not `fpdf2`

# Knowledge sources pinned and fresh
.venv/bin/python scripts/check-skill-freshness.py