feat: support API specs and Postman collections as targets

[5h4d0wr007]

Closes #844

Summary

Adds an api_spec target type so Strix can be pointed directly at an API contract instead of only crawling a live URL. The design is deliberately thin on the host: rather than parsing the spec into a normalized endpoint inventory, Strix copies the spec file into the sandbox and lets the agent read the full contract itself — so $ref, allOf, and nested schemas resolve properly and no detail is lost to a summarization step.

Three input forms, all via --target:

• OpenAPI 3.x / Swagger 2.0 file (.json / .yaml)
• Postman collection export (.json)
• Postman collection fetched live by id: postman://<collection-uuid>, optionally ?env=<environment-uuid> to resolve {{variables}} from a Postman environment

What the host actually does

Only three things happen host-side, in code — everything else about the contract is left to the agent:

1. Detect that a target is a spec (detect_spec_format: extension in .json/.yaml/.yml, then confirmed by content — openapi / swagger / _postman_id), so an arbitrary JSON config isn't mistaken for one.
2. Extract declared base URLs for scope authorization (spec_base_urls), because scope must be deterministic and can't be self-granted by the agent. OpenAPI servers templates are resolved to their variable defaults (https://{env}.api.example.com → https://staging.api.example.com); Swagger host/basePath/schemes and Postman {{baseUrl}}/request hosts are handled too. Unresolved/relative URLs are dropped so an unusable value is never authorized.
3. Fetch postman:// collections/environments (fetch_postman_collection / fetch_postman_environment) using POSTMAN_API_KEY, so the API key stays on the host and never enters the sandbox. A fetched collection is written to disk and then treated exactly like a local file.

The spec file is copied into a per-run staging dir exposed in the sandbox at /workspace/api-specs/<file> (duplicate names are disambiguated). The root task points the agent at that path, lists the authorized base URLs, and tells it to load the api_spec_testing skill and test every declared operation.

Scope model

Passing a spec authorizes the base URLs it declares as in-scope web_application targets; additional --target hosts are additive, like every other target type (a union, not an allow-list). This is what makes the spec-only workflow work — strix -t ./openapi.yaml or strix -t postman://<uid>?env=<env> with no separate host still has a reachable target. Pair a spec with an explicit --target https://api.example.com when you want to pin traffic to a deployed host.

Layout

• strix/utils/api_spec.py — detection, base-URL extraction, Postman fetch (the only host-side spec logic).
• strix/interface/utils.py — copies specs into the workspace staging dir / writes fetched collections.
• strix/interface/scan_setup.py — resolves local and postman:// specs during scan setup, records title + base URLs.
• strix/core/inputs.py — renders the spec into the root task and authorizes the declared base URLs.
• strix/skills/custom/api_spec_testing.md — spec-driven methodology (read the contract, prioritize authorization flaws, validate against the live host).
• POSTMAN_API_KEY wired into IntegrationSettings; pyyaml added for spec loading.
• Docs: README API-testing section, --target CLI help + docs/usage/cli.mdx, POSTMAN_API_KEY in docs/advanced/configuration.mdx.
• Tests: tests/test_api_spec.py (detection, loading, title, OpenAPI server-variable / Swagger / Postman base-URL extraction, Postman API status/error handling) and tests/test_api_spec_targets.py (target detection, setup-time resolution, staging/copy + duplicate names, root-task references, scope authorization).

Usage

# OpenAPI / Swagger or Postman collection file, paired with the live base URL
strix -t ./openapi.yaml -t https://api.example.com
strix -t ./collection.postman_collection.json -t https://api.example.com

# Postman collection pulled live by id (needs POSTMAN_API_KEY)
export POSTMAN_API_KEY="PMAK-..."
strix -t postman://<collection-uid>

# ...with a Postman environment to resolve {{baseUrl}} / token variables
strix -t "postman://<collection-uid>?env=<environment-uid>"

Notes / limitations

• Remote spec files by URL aren't auto-detected (local files only); the postman:// path covers the "no local file" case.
• Base URLs a spec declares as localhost aren't rewritten to the sandbox host gateway the way an explicit --target URL is — pass the reachable host explicitly in that case.

Link to Devin session: https://app.devin.ai/sessions/db75ac2e5685481f99961899932a7f84
Requested by: @0xallam

[greptile-apps]

Greptile Summary

Adds API-spec and Postman collection targets.

• Detects, fetches, stages, and renders API contracts for agent-driven testing.
• Derives declared API hosts for scan authorization and adds Postman configuration support.
• Adds documentation, methodology guidance, dependencies, and parser/target tests.

Confidence Score: 3/5

This PR is not safe to merge until explicit web targets actually prevent specification-declared hosts from expanding active-testing authorization.

The scope builder unconditionally authorizes every declared base URL even when the user supplied an explicit host allow-list, leaving the previously reported authorization failure reachable.

Files Needing Attention: strix/core/inputs.py

Security Review

Explicit web targets do not currently narrow specification-declared hosts, so an unrelated server URL in a supplied contract can still be authorized for active testing.

Important Files Changed

Filename	Overview
strix/core/inputs.py	Adds API-spec task and scope rendering, but declared hosts are still authorized without the promised explicit-target narrowing.
strix/interface/scan_setup.py	Resolves local and live Postman specifications before scan preparation and records their metadata.
strix/interface/utils.py	Adds API-spec target inference, Postman URI parsing, and staging helpers.
strix/utils/api_spec.py	Adds defensive OpenAPI, Swagger, and Postman recognition, host extraction, variable resolution, and Postman fetching.
strix/config/settings.py	Adds the Postman API key to integration settings.
tests/test_api_spec_targets.py	Exercises API-spec target resolution and wiring but does not establish the promised explicit-host narrowing in the implemented scope builder.

Prompt To Fix All With AI

### Issue 1
strix/core/inputs.py:173-176
**Explicit host allow-list is ignored**

When a scan supplies both an API specification containing an unrelated server URL and an explicit web target, this branch unconditionally adds every specification URL to `authorized_targets` without matching it against the explicit host. The scanner therefore remains authorized to actively test the unrelated host, leaving the scope-narrowing fix incomplete.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (2): Last reviewed commit: "refactor: relocate API-spec helpers to s..." | Re-trigger Greptile}

[bearsyankees]

@5h4d0wr007 i think the idea is great -- wanna review the greptile findings?

[5h4d0wr007]

@bearsyankees - these are all reviewed and updated. Please feel free to verify and re-run Greptile. Cheers!

[0xallam]

@greptile