Review an API for security
Lint the contract in every pull request, check staging’s traffic and each operation against it, and list the repository’s APIs with their owners.
You need the CLI installed; the Quickstart shows how. To run the commands as
written, download the Orders API as api/orders.yaml, and the
stand-in for its staging server as staging.yaml. The
contract has a token in a query string, an e-mail address in the URL and two operations with no
security requirement.
Lint for security and privacy
The recommended ruleset checks that each operation has a security requirement. The
privacy ruleset adds credentials and personal data in
URLs. URLs end up in server logs, browser history and Referer headers. Add both rulesets to
apigenie.yaml at the root of the repository:
version: '1.0'
commands:
lint:
extends: [recommended, privacy]
apigenie lint api/orders.yaml
19:11 warning Query parameter 'email' puts personal data (e-mail address) in the URL; send it in the request body instead privacy/no-personal-data-in-url
50:7 warning Security requirement is not defined operation-security-defined
68:7 warning Security requirement is not defined operation-security-defined
73:11 error Query parameter 'token' puts a credential (token) in the URL; send it in a header instead privacy/no-credentials-in-url
4 issues (1 errors, 3 warnings)
The command exits with 1 because of the error. Each rule’s page names the OWASP, CWE and GDPR
references it follows: privacy/no-credentials-in-url
and privacy/no-personal-data-in-url.
A parameter may be meant to carry a credential, such as the signature of a pre-signed download
link. Turn the rule off on that parameter with x-apigenie-lint-disable, or list its name in the
rule’s allow option.
To check 8 of the 10 risks of the OWASP API Security Top 10 (API1 to API5 and API7 to API9), add
the owasp ruleset:
extends: [recommended, privacy, owasp]. It has 32 rules. On this file it adds 42 issues, mostly
missing error responses, rate-limit responses and CORS headers. Turn it on when the team is ready
to work through them, and turn off the rules that
don’t apply to the API.
Put the findings in code scanning
With sarif: true, the GitHub Action uploads the findings to code scanning, where they show on the
pull request and stay in the Security tab until they’re fixed. Add
.github/workflows/api-security.yaml:
on: pull_request
permissions:
contents: read
security-events: write
jobs:
api-security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: mykulyak/api-genie-action@v0
with:
command: lint
files: api/**/*.yaml
config: apigenie.yaml
sarif: true
The Action’s code scanning section lists the permission
and the inputs. On another CI system, apigenie lint --formatter sarif api/orders.yaml > lint.sarif
writes the same file; see CI.
Rate the security of a change
apigenie diff rates a removed security requirement or a changed security scheme as breaking, so
an operation that turns public stops the pull request. Here a copy of the contract loses the
security of GET /orders, lines 16 and 17:
sed '16,17d' api/orders.yaml > changed.yaml
apigenie diff api/orders.yaml changed.yaml
changed.yaml
12 7 breaking Modified operation GET /orders
12 7 breaking Security requirements changed
The command exits with 1. The Catch breaking changes in CI guide adds it as a required check.
Check staging’s traffic at a proxy
A contract says what the API should do; staging shows what it does. Here the stand-in plays staging. It answers the contract’s operations, a token endpoint and a debug route the contract doesn’t declare:
apigenie-server staging.yaml --port 8080
Listening on http://127.0.0.1:8080/v1 (spec: staging.yaml, 5 operations)
Admin API: http://127.0.0.1:8080/__apigenie
Dashboard: http://127.0.0.1:8080/__apigenie/ui
In another terminal, put apigenie-server in front of it with --proxy-to. Every request goes to
staging, and both the request and staging’s response are checked against the contract:
apigenie-server api/orders.yaml --proxy-to http://localhost:8080 \
--report contract.json --record-har staging.har --fail-on errors
Listening on http://127.0.0.1:4010/v1 (spec: api/orders.yaml, 3 operations)
Proxy: http://localhost:8080 (requests: log, responses: log, unknown routes: forward, mode: always, HAR: staging.har)
Contract report: contract.json
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui
Point the integration tests, a scanner or a pentester’s browser at the proxy. Here, in a third
terminal, three requests stand in for the tests. The first has no token, the second has one, and
the third calls the debug route. The last command stops the proxy, which you can also do with
Ctrl+C in its terminal:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4010/v1/orders
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4010/v1/orders -H 'Authorization: Bearer test-token'
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4010/v1/internal/debug
curl -s -X POST http://127.0.0.1:4010/__apigenie/shutdown
401
200
200
The proxy’s terminal logs each exchange as it passes. When the proxy stops, it writes the reports and prints what it saw:
Contract: 3 requests (1 undocumented), 1 errors, 1 warnings
Coverage: 37.5% of 8 branches, 1 of 3 operations
not tested: GET /orders/{order_id} (getOrder), GET /exports (exportOrders)
undocumented: GET /v1/internal/debug (1)
error GET /orders: security: a bearer token (oauth) are missing (unauthorized; request.authorization.missing)
warn GET /v1/internal/debug: path: GET /v1/internal/debug matches no path of the document (unknown-path; request.path-or-method.unknown)
Contract failed: 1 error violations
undocumentedlists the routes staging answered that the contract doesn’t have: a debug endpoint, an old version, a route nobody wrote down.contract.jsonhas the same list underundocumented. The list holds only the routes the traffic reached. To block those routes at the proxy, setproxy.unknown_routes: rejectin the configuration.request.authorization.missingis a request without the credentials the operation requires. Withsecurity.mode: enforceand the credentials in the configuration, a wrong token is reported asrequest.authorization.rejected; see validation.--fail-on errorsmakes the proxy exit with 5 because of the error, which fails a CI job.
By default the proxy reports and forwards. It doesn’t check that staging refuses a request without credentials, or that a response holds no sensitive data. It sends no attack payloads either: injection and broken object-level authorization are still the pentest’s job.
Keep the evidence
staging.har holds every exchange through the proxy, with the violations of each, as HAR 1.2.
Browsers’ developer tools, Postman and HAR viewers read it. The values of Authorization,
Cookie, Set-Cookie, Proxy-Authorization and X-Api-Key are written as [redacted]:
grep -A1 '"name": "Authorization"' staging.har
"name": "Authorization",
"value": "[redacted]"
proxy.redact sets the list of headers. Query strings are not redacted. A token sent in a query
string stays in the file, as evidence of the privacy/no-credentials-in-url finding. Bodies up to
1 MiB are kept, binary ones in Base64; see contract testing.
To record whole sessions that the tests can replay later, use --record, and
--record-redact /password for values in bodies; see recording.
Send every operation a request with a token
The proxy checks the traffic it gets; apigenie test --generate makes the traffic. It sends one
request per operation, from the contract’s examples or generated from its schemas. Each request
carries a token from the OAuth 2 token endpoint, and each is checked against the contract. With
the stand-in still running:
apigenie test --spec api/orders.yaml --generate --base-url http://localhost:8080/v1 \
--header 'Authorization: oauth2 client_credentials' \
--var oauth2_tokenEndpoint=http://localhost:8080/v1/token \
--var oauth2_clientId=security-ci --var oauth2_clientSecret=$CLIENT_SECRET \
--var oauth2_scope=orders:read --report test.json
PASS GET http://localhost:8080/v1/orders -> 200 (0 ms) listOrders
PASS GET http://localhost:8080/v1/orders/8ccb4f4e-6b89-48ea-8990-5b35b895faf7 -> 200 (0 ms) getOrder
PASS GET http://localhost:8080/v1/exports?token=harum%20p -> 200 (7 ms) exportOrders
Requests: 3 passed, 0 failed, 0 skipped
Contract: 3 requests (0 undocumented), 0 errors, 2 warnings
Coverage: 75.0% of 8 branches, 3 of 3 operations
warn GET /orders/{order_id}: security: GET /orders/{order_id} declares no security requirement, but an OAuth 2 token is sent (oauth2-scheme; request.authorization.oauth2-scheme)
warn GET /exports: security: GET /exports declares no security requirement, but an OAuth 2 token is sent (oauth2-scheme; request.authorization.oauth2-scheme)
The two warnings are the operations the linter found without a security requirement, seen from the
traffic. request.authorization.oauth2-scope warns when the token’s scopes don’t match those an
operation declares. Where the client secret, the token or an Authorization value would appear
in the output or in test.json, it is written as [redacted]. The password and
refresh_token grants and OpenID Connect discovery are in
Variables and OAuth 2.
List the APIs and their owners
After an incident, the first question is which APIs there are, and who owns each.
apigenie-catalog (experimental, outside the 1.0 compatibility promise) answers it from the
repository, with nothing uploaded anywhere. Stop the stand-in, and delete changed.yaml and
staging.yaml: init would list them as APIs too. Commit api/orders.yaml (run git init first
if the directory isn’t a repository), so that list shows its last commit. Then:
apigenie-catalog init
apigenie-catalog (experimental, outside the 1.0 compatibility promise)
Updated /home/me/shop/apigenie.yaml: 1 added, 0 kept, 0 not found
added api/orders.yaml
init adds an entry per specification of the repository to apigenie.yaml, with owner: null.
Fill in the owner, then:
apigenie-catalog list
apigenie-catalog (experimental, outside the 1.0 compatibility promise)
NAME FORMAT VERSION OWNER PATH COMMIT
orders-api OpenAPI 3.1.0 1.4.0 team-commerce api/orders.yaml 6ced173 2026-11-08
--json prints it with a published schema, for a dashboard or an audit. The
Catalog the APIs of a repository guide keeps the
catalog current in CI.
Next steps
apigenie lint: rulesets, custom rules in Spectral’s format, and thesarifformatter.- Contract testing: every check of the validating proxy, and its reports.
- Mock and contract-test an API: the proxy as a contract test in CI.
- Review API security: what API Genie covers for AppSec and platform teams.