OWASP Top 10

A set of rules to help enforce the OWASP Top Ten security guidelines. These guidelines are defined in OWASP Top 10 and the rules to help enforce them are defined in GitHub.

To add a public style guide:

  1. Go to the Standardization page.

  2. Click Add Public Style Guides.

  3. Select an existing public style guide from the list in the Manage Public Style Guides modal window.

  4. Add it to your set of rules on the Standardization page.

    Note

    Preview takes you to the style guide documentation pages.

You then can:

  • Use the style guide as-is to automatically lint your API files.API Standardization

  • Disable individual rules that don't follow your organization's standards.

  • Customize severity of the rules to meet your needs.

icons03.png api2:2019-no-api-keys-in-url

The security scheme must not contain API Keys in query parameters.

API Keys are (usually opaque) strings that can be eavesdropped, especially when they are passed as URL parameters.

Invalid Example

The in:query setting makes this example invalid.

securitySchemes:
    API Key:
      name: API Key
      type: apiKey
      in: query

Valid Example

The in:header makes this example valid.

securitySchemes:
    API Key:
      name: API Key
      type: apiKey
      in: header

icons03.png owasp:api1:2019-no-numeric-ids

Path parameters must use random IDs that cannot be guessed, such as UUIDs.

Invalid Example

In this example, the {userId} parameter has a type of integer.

paths:
  '/users/{userId}':
    parameters:
      - schema:
          type: integer
        name: userId
        in: path
        required: true
        description: Id of an existing user.

Valid Example

In this example, the {userId} parameter has a type of string with a format of uuid.

paths:
  '/users/{userId}':
    parameters:
      - schema:
          type: string
          format: uuid
        name: userId
        in: path
        required: true
        description: Id of an existing user.

icons03.png owasp:api2:2019-auth-insecure-schemes

Security scheme must use a secure method.

negotiate and auth2 are considered to be insecure security schemes.

Invalid Example

This example is invalid because oauth is considered an insecure scheme.

securitySchemes:
   Oauth1:
     type: http
     scheme: oauth

Valid Example

securitySchemes:
   Bearer:
     type: http
     scheme: bearer

icons03.png owasp:api2:2019-jwt-best-practices

Security scheme description must state that the implementation conforms with JSON Web Tokens RFC7519, the JSON Web Token standard.

Invalid Example

This example is invalid because RFC8726 is not included in the security scheme description.

JWTBearer:
      type: oauth2
      flows:
        authorizationCode:
          ...
          ...
          ...
          ...
      description: A bearer token in the format of a JWS.

Valid Example

JWTBearer:
      type: oauth2
      flows:
        authorizationCode:
          ...
          ...
          ...
          ...
      description: A bearer token in the format of a JWS and conforms to the specifications included in RFC8725.

icons03.png owasp:api2:2019-no-credentials-in-url

Path parameter must not contain credentials, such as API key, password, or secret.

Invalid Example

This example is invalid because the path parameter includes a string with the name password.

paths:
  '/user/{password}':
    parameters:
      - schema:
          type: string
          format: password
        name: password
        in: path
        required: true

Valid Example

Remove the invalid path parameter.

paths:
  '/user/

icons03.png owasp:api2:2019-no-http-basic

Security scheme must not use basic auth. Use a more secure authentication method, such as OAuth 2.0.

Invalid Example

securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Valid Example

securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        ...
          ...
          ...
          ...
          ...

icons03.png owasp:api2:2019-protection-global-unsafe

POST. PUT, PATCH, and DELETE operations must be protected by a security scheme at either the global level or operation level.

Security rules are defined in the securityScheme section.

Valid Example: Global

securitySchemes:
    API Key:
      name: API Key
      type: apiKey
      in: header
security:
  - API Key: []

*Valid Example: Operation

paths:
  '/users/{userId}':
    patch:
      ...
      responses:
        ...
      security:
        - API Key: []

icons03.png owasp:api4:2019-array-limit

Array size should be limited to mitigate resource exhaustion attacks. This can be done using maxItems. You should ensure that the subschema in items is constrained too.

icons03.png owasp:api4:2019-integer-format

Integers should be limited to mitigate resource exhaustion attacks. Specifying whether int32 or int64 is expected via format.

icons03.png owasp:api4:2019-integer-limit

owasp:api4:2019-integer-limitArray size should be limited to mitigate resource exhaustion attacks. This can be done using maxItems. You should ensure that the subschema in items is constrained too.

icons03.png owasp:api4:2019-integer-limit-legacy

Array size should be limited to mitigate resource exhaustion attacks. This can be done using maxItems. You should ensure that the subschema in items is constrained too.

icons03.png owasp:api4:2019-rate-limit

Headers for 2xx and 4 xx responses must contain RateLimit-Limit, RateLimit-Reset, X-RateLimit-Limit, or X-Rate-Limit-Limit.

Proper rate limits avoid attackers overloading the API. There are many ways to implement rate-limiting, but most of them involve using HTTP headers, and there are two popular ways to do that:

Invalid Example

The 200 response does not contain rate-limiting headers.

responses:
'200':
   description: User Not Found

Valid Example

The 200 response contains rate-limiting headers.

responses:
  '200':
    headers:
      RateLimit-Limit:
        description: The number of allowed requests in the current period.
        schema:
          type: integer
      RateLimit-Reset:
        description: The number of seconds left in the current period.
        schema:
          type: integer

icons03.png owasp:api4:2019-rate-limit-retry-after

Headers for 429 responses must contain Retry-After.

Invalid Example

'429':
      description: Too Many Requests
      headers:
        RateLimit-Limit:
          ...
        RateLimit-Reset:
          ...

Valid Example

'429':
   headers:
    RateLimit-Limit:
      ...
    RateLimit-Reset:
      ...
    Retry-After:
      description: The number of seconds to wait before allowing a follow-up request.
        schema:
          type: integer

icons03.png owasp:api4:2019-string-limit

String size should be limited to mitigate resource exhaustion attacks. This can be done using maxLength.

icons03.png owasp:api4:2019-string-restricted

To avoid unexpected values being sent or leaked, ensure that strings have either a format or a RegEx pattern. This can be done using format or pattern.

icons01.png owasp:api3:2019-define-error-responses-401

Operation must have a 401 response defined.

Invalid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '501':
      description: Bad Gateway
      headers:
        ...

Valid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '429':
        ...
    '401':
      description: Not Authenticated
      headers:
        ...

icons01.png owasp:api3:2019-define-error-responses-500

Operation must have a response defined.

Invalid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '501':
      description: Bad Gateway
      headers:
        ...

Valid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '429':
        ...
    '500':
      description: Internal Server Error
      headers:
        ...

icons01.png owasp:api3:2019-define-error-validation

Operation must have a 400, 422 or 4xx response defined.

Invalid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '404':
      description: User Not Found
      headers:
        ...

Valid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '404':
      description: User Not Found
      headers:
        ...

icons01.png owasp:api4:2019-rate-limit-responses-429

Operation must have a 429 response defined.

Invalid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '431':
      description: Request Header Fields Too Large
      headers:
        ...

Valid Example

get:
  summary: Get User Info by User ID
  tags: []
  responses:
    '200':
       ...
    '400':
      ...
    '429':
      description: Too Many Requests
      headers:
        ...

icons01.png owasp:api6:2019-constrained-additionalProperties

By default JSON Schema allows additional properties, which can potentially lead to mass assignment issues, where unspecified fields are passed to the API without validation.

icons01.png owasp:api6:2019-no-additionalProperties

Object should not allow for additional properties, which can allow unspecified fields passed to the API without validation.

Invalid Example

In this example, additionalProperties are allowed on the object.

schemas:
   User:
     type: object
     title: User
      additionalProperties: true
      properties:
        id:
          type: integer
        firstName:
          type: string
        lastName:
          type: string

Valid Example

In this example, additionalProperties are not allowed on the object.

schemas:
   User:
     type: object
     title: User
     description: ''
      additionalProperties: false
      properties:
        id:
          type: integer
        firstName:
          type: string
        lastName:
          type: string

icons01.png owasp:api2:2019-protection-global-safe

GET and HEAD operations should be protected by a security scheme at either the global level or operation level.

Security rules are defined in the securityScheme section.

Invalid Example: Global

securitySchemes:
    API Key:
      name: API Key
      type: apiKey
      in: header
security:
  - API Key: []

Valid Example: Operation

paths:
  '/users/{userId}':
    get:
      ...
      responses:
        ...
      security:
        - API Key: []

icons01.png owasp:api2:2019-protection-global-unsafe-strict

POST, PATCH, DELETE, and PUT operations should be protected by a security scheme at either the global level or operation level.

Security rules are defined in the securityScheme section.

Invalid Example

The PATCH operation has an empty security value so it is not protected.

paths:
  '/users/{userId}':
    patch:
      ...
      responses:
        ...
      security:
      - []

Valid Example

The PATCH operation is protected by the API Key. As an alternative, remove the empty security setting at the operation level and use global security.

paths:
  '/users/{userId}':
    patch:
      ...
      responses:
        ...
      security:
        - API Key: []
In this section:
© 2024
Publication date: