# Review an API for security

Source: https://api-genie.dev/docs/guides/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](/docs/quickstart) shows how. To run the commands as
written, download the [Orders API](/samples/orders.openapi.yaml) as `api/orders.yaml`, and the
[stand-in for its staging server](/samples/orders-staging.openapi.yaml) 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](/docs/linter/openapi/rulesets/privacy) 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:

```yaml
version: '1.0'
commands:
  lint:
    extends: [recommended, privacy]
```

```sh
apigenie lint api/orders.yaml
```

```text
  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`](/docs/linter/openapi/rules/privacy-no-credentials-in-url)
and [`privacy/no-personal-data-in-url`](/docs/linter/openapi/rules/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](/docs/reference/cli/lint#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](/docs/reference/cli/lint#rules-and-severities) 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`:

```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](/docs/ci/github-action#code-scanning) 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](/docs/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:

```sh
sed '16,17d' api/orders.yaml > changed.yaml
apigenie diff api/orders.yaml changed.yaml
```

```text
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](/docs/guides/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:

```sh
apigenie-server staging.yaml --port 8080
```

```text
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:

```sh
apigenie-server api/orders.yaml --proxy-to http://localhost:8080 \
  --report contract.json --record-har staging.har --fail-on errors
```

```text
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:

```sh
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
```

```text
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:

```text
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
```

- `undocumented` lists the routes staging answered that the contract doesn't have: a debug
  endpoint, an old version, a route nobody wrote down. `contract.json` has the same list under
  `undocumented`. The list holds only the routes the traffic reached. To block those routes at the
  proxy, set `proxy.unknown_routes: reject` in the [configuration](/docs/reference/server/configuration).
- `request.authorization.missing` is a request without the credentials the operation requires.
  With `security.mode: enforce` and the credentials in the configuration, a wrong token is
  reported as `request.authorization.rejected`; see [validation](/docs/reference/server/validation).
- `--fail-on errors` makes 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]`:

```sh
grep -A1 '"name": "Authorization"' staging.har
```

```text
              "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](/docs/reference/server/contract-testing).
To record whole sessions that the tests can replay later, use `--record`, and
`--record-redact /password` for values in bodies; see [recording](/docs/reference/server/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:

```sh
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
```

```text
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](/docs/reference/cli/test/variables#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:

```sh
apigenie-catalog init
```

```text
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:

```sh
apigenie-catalog list
```

```text
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](/docs/guides/catalog-the-apis-of-a-repository) guide keeps the
catalog current in CI.

## Next steps

- [`apigenie lint`](/docs/reference/cli/lint): rulesets, custom rules in Spectral's format, and the
  [`sarif`](/docs/reference/cli/lint#sarif) formatter.
- [Contract testing](/docs/reference/server/contract-testing): every check of the validating proxy,
  and its reports.
- [Mock and contract-test an API](/docs/guides/mock-and-contract-test-an-api): the proxy as a
  contract test in CI.
- [Review API security](/use-cases/api-security): what API Genie covers for AppSec and platform
  teams.
