Picking the network,
one port at a time

An on-site pentest pipeline for authorised security professionals. Air-gapped, LLM-powered, and built to operate without leaving a trace.

AI-agent friendly — works with Hermes Agent, Claude Code, or any CLI-capable assistant. Guided phase gates, report drafting, and decision support.

Get Started Learn More
Features

Built for the field

PortShim is designed for on-site operations where every second counts and every packet matters.

⚡

6-Phase Pipeline

Phase 0 (Scope) through Phase 5 (Retest). Each phase ends with a review gate - APPROVE, RERUN, MODIFY SCOPE, or ABORT.
🔌

Air-Gapped Operations

Runs entirely on local LLMs via llama.cpp with Vulkan GPU offload. Three local models per phase - no internet required.
🧩

Engagement Profiles

Three noise profiles (Silent Entry, Surgical, Full Assault) control how aggressively tools probe the target. Set once per engagement.
📊

Multi-Format Reports

DOCX (branded), PPTX (6-slide exec brief), PDF (weasyprint), XLSX (severity-coloured checklist) - all from one command.
🛡️

Server Lifecycle

Built-in portshim CLI manages llama-server: start, stop, restart, status, model switching. Auto-starts on scan for local mode.
📊

Structured Gate Reviews

Gate 1 uses topology.py --gate1 for complete, never-truncated host summaries from XML. No more missing hosts in truncated output.
📡

Wireless Assessment

Discover, select, and assess nearby access points without dropping your network connection. Auto-fallback to managed mode, with --force for full airodump-ng monitoring.
How It Works

The 6 Phases of PortShim

Each phase has a clear goal, a defined model assignment, and a gate condition before moving to the next.

0

Scope & Setup

Bootstrap environment, sync knowledge bases, configure engagement profile (Silent Entry / Surgical / Full Assault) and LLM mode (local / hybrid / cloud).

1

Reconnaissance

nmap sweep (all ports, OS detection, service versioning), device classification (40+ roles), topology mapping. Gate 1 uses topology.py --gate1 for complete host summaries from XML.

2

Vulnerability Analysis

CVE cross-reference via nmap-vulners NSE, nuclei deep-scan, CVSS v3.1 scoring. Prioritised findings list with exploit availability markers.

3

Exploitation

Hydra brute-force, paramiko SSH automation, manual probe of discovered services (telnet, HTTP, UPnP). SuperGemma4 26B for exploit analysis. Non-destructive escalation only.

4

Reporting

Multi-format deliverables from one command: DOCX (branded, Calibri font, A4), PPTX (6-slide exec brief), PDF (weasyprint, A4), XLSX (severity-coloured checklist with dropdowns).

5

Retest

Rescan after remediation, compare baseline vs retest, auto-classify as FIXED / STILL OPEN / NEW / REGRESSION. Update checklist with retest status.

Requirements

What you need to run PortShim

Designed for a field laptop with a capable GPU. All dependencies are local — no cloud required.

Hardware

  • AMD Radeon 8060S / NVIDIA RTX 3090+ (24 GB VRAM)
  • 64 GB RAM recommended
  • 50 GB+ free disk for models
  • Linux (macOS partial, Windows via WSL2)

Software

  • llama.cpp b9870+ (Vulkan or CUDA)
  • Python 3.11+
  • nmap, hydra, sshpass (via deploy.py)
  • nuclei, httpx (Go tools, via deploy.py)

Models

  • Qwen3-Coder 30B (Q4_K_M) — recon & CVE analysis
  • SuperGemma4 26B (Q4_K_M) — exploitation & reports
  • HauhauCS 35B (Q4_K_S) — alternative exploit

Network

  • Target network access (authorised)
  • USB-to-Ethernet adapter for wired scanning — Dell USB-C (Realtek RTL8153) recommended. D-Link DUB-1312 as backup. Avoid ASIX on generic cdc_ncm driver.
  • USB Wi-Fi adapter (Alfa AWUS036ACH — RTL8812AU, more)
  • No internet required for local mode
Quick Start

Get PortShim running in minutes

Start the server, load a model, and run your first scan analysis.

# Clone and bootstrap
git clone https://github.com/ozdemir-mehmet/portshim
cd portshim
python deploy.py

# Optional: exploit framework (1GB+)
python deploy.py --with-msf
# Start with Phase 1 model (Qwen3-Coder)
python portshim server start --model qwen3-coder-30b-a3b-instruct

# Start with exploit model (SuperGemma4)
python portshim server start --model supergemma4-26b-uncensored

# Server lifecycle
python portshim server status
python portshim server restart --model qwen3-coder-30b-a3b-instruct
python portshim server models
python portshim server stop
# One-command engagement
python portshim scan 10.0.0.0/22

# Air-gapped mode (local LLM only)
python portshim scan 10.0.0.0/22 --mode local --engagement full-assault

# Generate reports
python skills/site-assessment-pipeline/scripts/report-gen.py \
  outputs/phase4-findings.json --output-dir outputs/reports --format all
# Discover APs (safe mode — auto-fallback to iw dev scan)
portshim wireless scan

# Full monitor mode scan (drops network)
portshim wireless scan --force --duration 30

# Select targets interactively
portshim wireless select

# Auto-select top 3 strongest APs
portshim wireless select --auto --max 3

# Assess current status of selected targets
portshim wireless assess
FAQ

Common questions

PortShim is purpose-built for on-site, air-gapped operations. Instead of relying on cloud LLMs, it runs fully on a local GPU using llama.cpp. The 6-phase pipeline with per-phase model selection means you're never using a slow model for a fast task, and never using a censored model for an exploit phase.
Yes. PortShim supports a hybrid mode — use DeepSeek or another cloud API for reporting and CVE analysis, while keeping exploitation fully local to avoid API refusals on exploit-specific prompts. See llm-config.py hybrid.
The benchmarked stack is: Qwen3-Coder 30B (recon & CVE analysis, 447 PP tok/s), SuperGemma4 26B (exploitation & reports, 525 PP tok/s), and HauhauCS 35B (alternative exploit, 481 PP tok/s). All are Q4_K_M (Q4_K_S for HauhauCS) GGUF files running on Vulkan at 16K context.
PortShim is designed for authorised security professionals. You should be comfortable with nmap, basic exploitation concepts, and command-line tooling. The pipeline automates the heavy lifting, but operator judgement is required at every phase gate.
Yes. PortShim is agent-agnostic — the --force flag and structured output work with any AI assistant. It pairs naturally with Hermes Agent for interactive phase-by-phase orchestration, and works equally well with Claude Code, Codex, OpenAI CLI, or custom agent workflows. The agent guides you from scope confirmation through to final retest, presents findings at each gate, and waits for your approval before advancing. Common workflows include:

End-to-end assessment — Bootstrap via deploy.py, then hand off to the agent. It walks through network discovery, vulnerability correlation, and exploitation in a structured, auditable flow with operator decisions at every stage.

Report-driven operations — After an assessment, the agent helps draft narrative executive summaries, populate remediation checklists, and generate multi-format deliverables from the raw findings — all while keeping you in the approval loop.

Adversary-simulation scenarios — For red team exercises, the agent adapts stealth profiles and LLM modes between phases, supports wireless testing scope changes mid-engagement, and maintains an evidence trail suitable for after-action reviews.
No. In fully-local mode, everything runs on your laptop — model inference, CVE database lookups (pre-synced), and report generation. Internet is only needed for initial model downloads and optional cloud API fallback.
A shim is a thin tool used in lockpicking to bypass wafer locks by sliding between the plug and the bible. In networking, a shim sits between layers to intercept or modify traffic. PortShim picks the network — hence the name.
No — not by default. PortShim detects if your Wi-Fi adapter carries your internet connection and automatically uses managed mode (iw dev scan) to avoid disconnecting you. You get full AP discovery (SSIDs, BSSIDs, signal, encryption) without losing connectivity.

If you specifically need monitor mode (for handshake capture or deauth), pass --force. A warning explains the trade-off before proceeding. After the operation, the interface is restored to managed mode and PortShim attempts to reconnect.

For dedicated wireless testing without any risk to your network connection, connect an external USB adapter — PortShim will prefer it automatically.
Download the GGUF file to ~/local-models/<model-name>/, start the server, and run python scripts/benchmark-models.py --local-only. See the benchmark reference for details.
Yes — do not scan a wired network over WiFi. ARP-based discovery won't work across the AP boundary. Any USB-to-Ethernet adapter works, but we recommend the Dell USB-C adapter (Realtek RTL8153) — it uses the in-kernel r8152 driver with full hardware offload. The D-Link DUB-1312 (ASIX AX88179) is a good backup but verify it's on the ax88179_178a driver, not the generic cdc_ncm. Avoid scanning through USB-C dock Ethernet if possible — the shared DisplayLink bus causes packet drops under load.