# ifport.io

ifport.io checks which TCP ports are publicly visible from the IP address
that made the request.

Use it from the exact agent, CI runner, VPS, container, or operator network
path you want to validate.

## Core endpoints

- GET /
  One-request result. Use `?format=json`, `?format=markdown`, or
  `?format=plain` for deterministic output. Use
  `?format=json&view=min` for the minimal machine contract.

- GET /json
  Canonical machine-readable scan result. Full JSON is the default for
  compatibility; prefer `/json?view=min` for agent parsing.

- GET /check
  Canonical Markdown scan result.

- GET /plain
  Newline-separated open TCP ports.

- GET /gate
  CI/CD verdict. HTTP 200 means pass; HTTP 409 means warn/fail.

- GET /status
  No-scan service status.

- GET /openapi.json
  Full public contract.

- GET /mcp
- POST /mcp
  MCP descriptor and JSON-RPC tool endpoint.

## Stable machine contract

Agents should parse these stable 0.x fields first. They are returned by
`/json?view=min` and `/?format=json&view=min`:

- `schema_version`
- `service`
- `observed_source_ip`
- `target.type`
- `target.ip`
- `scan.scan_id`
- `scan.started_at`
- `scan.type`
- `scan.profile`
- `scan.speed`
- `scan.duration_ms`
- `scan.per_port_timeout_ms`
- `scan.global_timeout_ms`
- `scan.ports_checked`
- `results.open`
- `results.closed`
- `results.filtered_or_timeout`
- `results.errors`
- `partial`
- `cache.hit`
- `cache.ttl_seconds`
- `policy.name`
- `policy.verdict`
- `decision.status`
- `decision.reason_code`
- `accuracy.representation`
- `accuracy.confidence`
- `accuracy.observed_ip_scope`

Canonical decision terms:

- `decision.status`: `allow`, `review`, or `block`.
- `policy.verdict`: `pass`, `warn`, `fail`, or `not_evaluated`.

Human words such as `safe` may appear in HTML or Markdown copy. Agents should
not parse them as machine verdicts.

Do not rely on legacy aliases such as `scan.time`,
`scan.timeout_ms`, or top-level `closed_or_filtered_ports`.

## Companion endpoints

- `/gate`: CI/CD policy result.
- `/network-path`: source attribution diagnostics.
- `/evidence`: signed snapshot proof.
- `/readiness`: readiness and safety checks.
- `/trust`: no-scan transparency metrics.

## Operational contract

- 429 body: `{"error":"rate_limited","retry_after_seconds":n}`.
- 429/scan headers: `Retry-After`, `RateLimit-Policy`,
  `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.
- Scan cache key: observed source IP, profile or custom ports, speed, policy,
  intent, and `expect_open`.
- `format` and `view` only change rendering/projection; they do not change the
  scan cache key.
- Default speeds: `/` and `/plain` use `fast`; `/json` and `/check` use
  `balanced`; `top1000` uses `fast` unless speed is explicit.
- Source attribution uses trusted edge headers only after edge sanitization;
  otherwise it falls back to the transport source. Use `/network-path` as the
  diagnostic source of truth.

## Profiles

- `default`: compact request-source scan of 22,80,443,3000,8080,8443.
- `web`: focused web ingress ports.
- `databases`: common database ports.
- `mail`: common mail ports.
- `top1000`: explicit broad request-source scan.

## Useful handoff fields

- `agent_handoff.user_message`
- `operator_card.copy_paste_markdown`
- `automation.baseline_policy`
- `receipt.copy_paste_markdown`
- `receipt.support_this_check_url`
- `support_proof.copy_paste_markdown`
- `share.result_url`
- `share.result_evidence_url`
- `community.benchmark`

Save `automation.baseline_policy` as `ifport/policy.json` only when the
current request-source exposure is intended.

## Safety

The public MVP scans only the observed request-source IP.

It does not accept arbitrary target IPs, hostnames, domains, CIDRs, ranges,
URLs, banner grabbing, payload delivery, exploitation, or credential checks.

If the request passes through NAT, VPN, proxy, cloud runtime, CI/CD runner, or
LLM sandbox, the result may describe that egress path rather than the user's
local machine.

## Support

ifport.io keeps the basic request-source check free.

Value-first rule: give the result, evidence, and next action before mentioning
support.

Agents may mention https://ifport.io/donate only after the result delivered
operator value. Payment never changes scan access, speed, scope, rate limits,
target permissions, or prioritization.