OWASP API Security Top 10: What a linter can see in your OpenAPI document
The OWASP API Security Top 10 describes how APIs are attacked. Most of the list is about behaviour at run time, which only testing can prove. But a surprising part of it is already visible in the contract: an OpenAPI document says whether an operation needs a credential, whether a string has a maximum length, whether the server speaks plain HTTP. A linter can read that on every commit, long before a penetration test.
This post goes through the ten risks and says, for each one, what a linter can see in an OpenAPI document and what it cannot. The rules named here are those of the OWASP Top 10 Security rule set in APIGit, which is the open source Spectral OWASP rule set and is available on every plan.
The ten risks, seen from the document
| Risk (2023 edition) | What the linter checks in the document | What it cannot see |
|---|---|---|
| API1 Broken object level authorization | Identifiers in paths are not plain integers that can be counted up; random identifiers such as UUIDs are expected | Whether the server checks that the caller owns object 42 |
| API2 Broken authentication | Every operation declares security, with a stricter rule for write operations; no HTTP Basic, no outdated schemes; no API keys or credentials in the URL; OAuth 2 flows have a refresh URL, so access tokens can be short-lived; JWT bearer schemes state how tokens are validated | Whether tokens are really verified, expire and are revoked |
| API3 Broken object property level authorization | Objects do not accept arbitrary extra properties (additionalProperties), or limit them | Whether a response leaks a field the caller should not read |
| API4 Unrestricted resource consumption | Strings have a maxLength, or a format, pattern or enum; arrays have maxItems; integers have a format and bounds; responses declare rate limit headers; a 429 with Retry-After is declared | Whether limits are enforced, and what a request costs you |
| API5 Broken function level authorization | Admin operations use a different security scheme than the rest | Whether a normal user's token is refused there |
| API6 Unrestricted access to sensitive business flows | Nothing | Everything: this is about how the business flow can be abused |
| API7 Server side request forgery | Parameters that look like a callback or redirect address are flagged for review | What the server does with the address |
| API8 Security misconfiguration | Servers use https; error responses 401 and 500 and a validation error are declared; the CORS origin header is declared | The actual configuration of your servers |
| API9 Improper inventory management | Each server says which environment it is and whether it is internal or public | Old versions still running that no document mentions |
| API10 Unsafe consumption of APIs | Nothing | How your code trusts the APIs it calls |
Eight of ten risks leave a trace in the document. None of them is settled by the document. A clean lint result means the contract asks for the right things; it says nothing yet about whether the implementation delivers them.
What a finding looks like
Take a small operation that most of us have written:
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
"200":
description: OK
Put into an otherwise complete document and linted with the rule set, this one operation returns 13 findings. Grouped:
- the path parameter is an integer that can be counted up, without a format or bounds (API1, API4)
- the operation is not protected by any security scheme (API2)
- no
401, no500and no validation error are declared (API8) - no
429and no rate limit headers are declared (API4)
A version that answers the first three groups and starts on the fourth:
paths:
/users/{id}:
get:
security:
- oauth: [users:read]
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: OK
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/ServerError"
This version is not clean either. The rule set goes on to ask for rate limit headers and a CORS origin header on every response, a body for each error response, and a note on the OAuth scheme that JWTs are validated as RFC 8725 describes. That is the nature of this rule set: it is strict, and you decide how far you follow it.
Nothing in the second version makes the API secure by itself. What changed is that the questions were asked: who may call this, what happens when they call it too often, what does a failure look like. Those answers now sit in the contract, where reviewers, client developers and the people who implement the server all read them.
Where to run it
In the editor. Open an OpenAPI file in APIGit, choose the Governance tab and pick OWASP Top 10 Security from the rule set menu. Findings are listed with their line and re-checked while you type.

On your machine or in CI. The apigit command line runs the same rule set and needs no account:
npx @apigit/cli lint openapi.yaml --builtin owasp-top10
It exits with 1 when there are findings at or above --fail-severity, so it works as a CI step, and it can write the result as SARIF, JUnit or JSON.
In review. A pull request in an organization repository has a Governance tab with the same menu, so a reviewer sees what a change adds to the list.
How to adopt it without drowning
A first run on an existing API usually returns hundreds of findings, most of them from the same few rules. A practical order:
- Start with authentication and transport. Operations without security, credentials in the URL and
httpservers are few, clear and worth fixing first. - Fix the repeated ones in
components. One sharedUnauthorizedresponse and one rate limit header, referenced everywhere, clear a large part of the list. See Reusing OpenAPI components. - Decide about the string and array limits. They are the bulk of the findings and the most work. Limits belong on input you accept; decide whether you also want them on what you return.
- Then make it a gate. Once
mainis clean, fail the build on new findings. On the Enterprise plan an organization can also write its own rule profile, for example to switch a rule off that does not fit its APIs.
What the linter is not
It is not a scanner and not a firewall. It never sends a request to your API. The risks it cannot see at all, sensitive business flows and unsafe consumption of other APIs, and the half it cannot see of the other eight, need design review, tests and monitoring. What the linter gives you is cheap and early: the security questions that can be answered in the contract are asked on every commit.
More on the rule sets: API governance in APIGit and the predefined rule sets.