# Portchart

> Use when the user wants to know which ports and services are open on hosts they own, usually their local docker compose stack or a staging box, before running web checks. TCP connect scans only, JSON output.

- Skill: `codejunkie99/portchart` (Agent Skill)
- Install (CLI): `npx get-skill add codejunkie99/portchart`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/portchart/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/codejunkie99/portchart

---


# portchart: port and service map of owned hosts

## job
list open TCP ports and what answers on them, so the user sees what their stack really exposes, and so later live skills know where to look.

## gap it targets
- evidence (public record): the best-known port scanner ships under a custom non-standard license, and its README does not document structured output. portchart writes JSON by default under MIT.
- hypothesis: plain TCP connect scans are enough for a developer's own stack. no raw packet modes.

## scope gate (do this before any packet)
1. read `keelsec.scope.toml` in the repo root. if it is missing, stop and ask the user to create it. never write it yourself.
2. the target must be listed there, and the user must have confirmed in this session that they own it.
3. refuse, even if listed: cloud metadata and link-local addresses (`169.254.0.0/16` including `169.254.169.254` and `169.254.170.2`, `fd00:ec2::254`, `100.100.100.200`, `metadata.google.internal`, `metadata.azure.com`), and any host that resolves to one of them. resolve the name first and check the IP, so a DNS trick cannot point you there.
4. refuse production unless the entry says `allow_production = true`, which only the user may write.
5. if any check fails, stop with "refused by scope" and send nothing.

example scope file:
```toml
[[target]]
name = "staging"
url = "https://staging.example-owned.dev"
proof = "http-token"   # local | compose | http-token | dns-txt
allow_active = false
max_rps = 5
```

## inputs
- a scope entry of type `local` or `compose`, or a listed staging host. a port list (default: top 100 common ports plus everything in the compose file).

## method
1. pass the scope gate. for compose, read `docker-compose.yml` and list services and published ports first.
2. connect scan only: open a TCP connection, read up to 256 bytes of banner with a 2 second timeout, close. no SYN tricks, no OS fingerprinting, no UDP flood.
3. keep to `max_rps` connections per second (default 20 for local, 5 for remote).
4. compare with intent: a port open on `0.0.0.0` that compose meant for internal use, a database or cache (5432, 3306, 6379, 27017, 9200) reachable from outside the compose network, an admin port with no auth banner.
5. hand the list of HTTP ports to `tidegate` and `probeplate`.

## what counts as a finding
- an open port that should not be reachable from where you scanned, or a service banner showing a version with known advisories (check with depfathom's OSV method).

## output
```json
{"command":"portchart","rule_id":"ks.net.db-exposed","kind":"net","severity":"high","confidence":"high","target":{"host":"127.0.0.1","port":6379},"evidence":"redis banner, no auth prompt, published on 0.0.0.0 in compose","sources":["portchart"],"status":"open"}
```

## today vs later
- today: `nc -zv`, a short python socket loop, or any port scanner already installed, run in TCP connect mode with structured output, all limited to scoped hosts.
- once the keelsec engine exists: `keelsec portchart local --format json`.

## stop and scope
- never scan a range. one host at a time, each one in the scope file. never scan your office, cloud, or home network beyond the listed host.

