Tutorial: API + OpenAPI seed

When the target is an API rather than a website, the right starting point isn’t a crawler — it’s the spec the API team already maintains. Pencheff imports OpenAPI 3.x, Swagger 2.0, and Postman v2.1 collections; every endpoint becomes a seed for the scanner without any HTML scraping.

Scenario

Target. https://api.acme.com/v1
Spec. openapi.json exported from the team’s build.
Auth. Bearer token via Authorization header.
Goal. Hit every documented endpoint with parameter-aware payloads, including BOLA / mass assignment / IDOR variants.

1. Import the spec

import_api_spec(session_id=sid,
                spec_path="./openapi.json",
                base_url="https://api.acme.com/v1")
→ "imported 84 endpoints across 12 tags"

The importer canonicalises paths, expands $ref, and seeds every operation as a known endpoint with its parameter shape.

2. Scan with the seeded endpoints

pencheff scan \
  --target https://api.acme.com/v1 \
  --profile standard \
  --token "$ACME_API_TOKEN" \
  --output ./reports/ \
  --format docx

standard against an API target enables scan_api — the module that owns BOLA, mass assignment, broken object property authorization, GraphQL introspection, and the rest of OWASP API Security Top 10 (2023). The seeded endpoints from step 1 are discovered automatically when the target carries an attached spec.

3. What `scan_api` does that DAST doesn’t

Test	What it does
BOLA / IDOR	Iterates `id` path params with a second user’s id
Mass assignment	Adds `is_admin: true` (and similar) to every PUT / PATCH body
Broken object property authz	Finds endpoints that reveal fields the caller’s role shouldn’t see
GraphQL introspection	Fingerprints the schema, then re-runs all the API tests against discovered fields
Schema-vs-implementation drift	Sends bodies the spec says are invalid — if the API accepts them, that’s a finding

4. Two credentials, real authz testing

Cross-tenant access tests need a second credential set. The multi-credential surface lives on the target, not as a CLI flag:

Dashboard. The target’s Credentials card supports a named set per role (default, admin, readonly, …). The scanner walks every endpoint with each credential when more than one is defined.
MCP host. Each credential set is added to the running session via the credential-store tools; the next scan_authz run will diff results across them.

The engine flags any case where User A can read or modify resources owned by User B.

5. Verify the report

The DOCX appendix “Endpoints scanned” lists every imported endpoint with its tested parameters and the verdicts.
Findings carry the OpenAPI operationId so a developer can jump straight to the failing handler.
The compliance rollup at /scans/{id}/compliance filters by framework — A01: Broken Access Control lights up first for BOLA-heavy APIs.

Postman collections work too. Same flag, same shape: --spec ./acme.postman_collection.json. The importer detects the format from the file body.

Deliverable

A DOCX report keyed to OpenAPI operationIds plus a JSON dump that keys findings by (operationId, parameter) for triage in the team’s issue tracker.

Tutorial: Web app pentest — for sites without a spec.
Plugin SDK: writing a custom API check — when the built-in matrix doesn’t cover your bespoke authz model.

SPA + authenticated crawl AI target provider examples