PortKeep

SKILL.md

# PortKeep

Port management + security for self-hosted infrastructure.

## When to use

- User asks about open ports, listening services, or what's running on a port
- User wants to audit their network security or attack surface
- User needs to claim/register a port to prevent conflicts
- User wants to check for port drift (declared vs actual ports)
- User mentions threat intel, C2 detection, or CVE exposure on their ports
- User wants to monitor ports across multiple nodes

## Install

```bash
brew tap jchandler187/tap
brew install portkeep
```

Or download from https://github.com/jchandler187/portkeep/releases/latest

## Commands

| Command | What it does |
|---------|-------------|
| `portkeep scan` | Discover all listening ports |
| `portkeep scan --node NAME` | Scan a remote node via SSH |
| `portkeep audit` | Security audit — score, C2 matches, CVEs, firewall |
| `portkeep sync` | Fetch and cache threat intel (9 sources) |
| `portkeep claim 3000 "api"` | Register a port as expected |
| `portkeep claim next` | Find next available port |
| `portkeep drift` | Declared vs actual — exits 1 on drift (cron-ready) |
| `portkeep list` | List all registered claims |
| `portkeep history` | Port change timeline |
| `portkeep node add NAME --host IP` | Add a remote node |
| `portkeep daemon start` | Background monitoring service |

All commands support `--json` for scripting and `--quiet` for cron.

## Threat Intel Sources

6 work out of the box (no API key):
- CISA-KEV, EPSS, Feodo Tracker, blocklist.de, Emerging Threats, DShield/SANS

3 require a free abuse.ch Auth-Key:
- ThreatFox, URLhaus, MalwareBazaar

Set `ABUSE_CH_AUTH_KEY` in environment to enable all 9.

## Examples

```bash
# First run — sync threat intel, then audit
portkeep sync
portkeep audit

# Register your services
portkeep claim 22 "ssh"
portkeep claim 3000 "grafana"
portkeep claim 8080 "api"

# Check for unexpected ports (great for cron)
portkeep drift

# Add a second machine
portkeep node add prod --host 10.0.0.5 --ssh-key ~/.ssh/id_ed25519
portkeep scan --node prod
```