shieldfy/api-security-checklist

Checklist of the most important security countermeasures when designing, testing, and releasing your API

繁中版 | 简中版 | العربية | Azərbaycan | বাংলা | Català | Čeština | Deutsch | Ελληνικά | Español | فارسی | Français | हिंदी | Indonesia | Italiano | 日本語 | 한국어 | ພາສາລາວ | Македонски | മലയാളം | Монгол | Nederlands | Polski | Português (Brasil) | Русский | ไทย | Türkçe | Українська | Tiếng Việt

API Security Checklist

Checklist of the most important security countermeasures when designing, testing, and releasing your API.

---

Authentication

• Don't use Basic Auth. Use standard authentication instead (e.g., JWT).
• Don't reinvent the wheel in Authentication, token generation, password storage. Use the standards.
• Use Max Retry and jail features in Login.
• Use encryption on all sensitive data.

JWT (JSON Web Token)

• Use a random complicated key (JWT Secret) to make brute forcing the token very hard.
• Don't extract the algorithm from the header. Force the algorithm in the backend (HS256 or RS256).
• Make token expiration (TTL, RTTL) as short as possible.
• Don't store sensitive data in the JWT payload, it can be decoded easily.
• Avoid storing too much data. JWT is usually shared in headers and they have a size limit.

Access

• Limit requests (Throttling) to avoid DDoS / brute-force attacks.
• Use HTTPS on server side with TLS 1.2+ and secure ciphers to avoid MITM (Man in the Middle Attack).
• Use HSTS header with SSL to avoid SSL Strip attacks.
• Turn off directory listings.
• For private APIs, allow access only from safelisted IPs/hosts.

Authorization

OAuth

• Always validate redirect_uri server-side to allow only safelisted URLs.
• Always try to exchange for code and not tokens (don't allow response_type=token).
• Use state parameter with a random hash to prevent CSRF on the OAuth authorization process.
• Define the default scope, and validate scope parameters for each application.

Input

• Use the proper HTTP method according to the operation: GET (read), POST (create), PUT/PATCH (replace/update), and DELETE (to delete a record), and respond with 405 Method Not Allowed if the requested method isn't appropriate for the requested resource.
• Validate content-type on request Accept header (Content Negotiation) to allow only your supported format (e.g., application/xml, application/json, etc.) and respond with 406 Not Acceptable response if not matched.
• Validate content-type of posted data as you accept (e.g., application/x-www-form-urlencoded, multipart/form-data, application/json, etc.).
• Validate user input to avoid common vulnerabilities (e.g., XSS, SQL-Injection, Remote Code Execution, etc.).
• Don't use any sensitive data (credentials, Passwords, security tokens, or API keys) in the URL, but use standard Authorization header.
• Use only server-side encryption.
• Use an API Gateway service to enable caching, Rate Limit policies (e.g., Quota, Spike Arrest, or Concurrent Rate Limit) and deploy APIs resources dynamically.

Processing

• Check if all the endpoints are protected behind authentication to avoid broken authentication process.
• User own resource ID should be avoided. Use /me/orders instead of /user/654321/orders.
• Don't auto-increment IDs. Use UUID instead.
• If you are parsing XML data, make sure entity parsing is not enabled to avoid XXE (XML external entity attack).
• If you are parsing XML, YAML or any other language with anchors and refs, make sure entity expansion is not enabled to avoid Billion Laughs/XML bomb via exponential entity expansion attack.
• Use a CDN for file uploads.
• If you are dealing with huge amount of data, use Workers and Queues to process as much as possible in background and return response fast to avoid HTTP Blocking.
• Do not forget to turn the DEBUG mode OFF.
• Use non-executable stacks when available.

Output

• Send X-Content-Type-Options: nosniff header.
• Send X-Frame-Options: deny header.
• Send Content-Security-Policy: default-src 'none' header.
• Remove fingerprinting headers - X-Powered-By, Server, X-AspNet-Version, etc.
• Force content-type for your response. If you return application/json, then your content-type response is application/json.
• Don't return sensitive data like credentials, passwords, or security tokens.
• Return the proper status code according to the operation completed. (e.g., 200 OK, 400 Bad Request, 401 Unauthorized, 405 Method Not Allowed, etc.).

CI & CD

• Audit your design and implementation with unit/integration tests coverage.
• Use a code review process and disregard self-approval.
• Ensure that all components of your services are statically scanned by AV software before pushing to production, including vendor libraries and other dependencies.
• Continuously run security tests (static/dynamic analysis) on your code.
• Check your dependencies (both software and OS) for known vulnerabilities.
• Design a rollback solution for deployments.

Monitoring

• Use centralized logins for all services and components.
• Use agents to monitor all traffic, errors, requests, and responses.
• Use alerts for SMS, Slack, Email, Telegram, Kibana, Cloudwatch, etc.
• Ensure that you aren't logging any sensitive data like credit cards, passwords, PINs, etc.
• Use an IDS and/or IPS system to monitor your API requests and instances.

---

See also:

• yosriady/api-development-tools - A collection of useful resources for building RESTful HTTP+JSON APIs.

---

Contribution

Feel free to contribute by forking this repository, making some changes, and submitting pull requests. For any questions drop us an email at [email protected].

api-security-checklist's Issues

Correlation with external (prior) guidelines

E.G:

• OWASP Security Coding Practices
• HTTP API Design

Aps security

Should add "Content-Disposition" to response header?

It's better to add Content-Disposition: attachment; filename="api.json" to response header in the case that some browsers had the vulnerability of nosniff bypass. But for keeping this guideline simple, maybe this shouldn't be added. How do you think?

Why 'Do not forget and leave the DEBUG mode on.' ?

If I leave DEBUG mode on, my api will generate tons of log

Suggestion: Always set charset in response header

http://blog.portswigger.net/2016/11/json-hijacking-for-modern-web.html

Also contains other helpful hints too

curious about "don't return security token"

how are we supposed to get the token to the authenticated user after authentication?

PUT mentioned, but PATCH is probably a better choice

The HTTP method PATCH might not be in the standard yet, but it's widely used. It would be good to mention it, as it makes partial updates "possible".

Reference: https://tools.ietf.org/html/rfc5789

What about GraphQL?

Hello,

It seems that this repository was made only for RESTful APIs. Maybe it would be nice to add a section for GraphQL, which is a nice alternative to REST.

What do you think?

Is use sha1 sign to verify a parameter in the request safe?

I have a project that our API should verify a parameter which is about the trade.
We use a method like the demo.
Demo
Request:
Host:192.168.0.1
parameters: sign - To verify the parameter
tradeinfo
sign = sha1(secretKey + tradeinfo + secretKey);

Please pay attention to this repo again

Hi, thx for ur exciting work! This checklist helped me very much.

But I noticed that this repo has had 9 issues & 9 pull requests(including mine) now, which still waiting for a reply.

So, let's make this repo be fashionable again. 😁

request integrity & replay

no word about request integrity

• http-cavage,
• IETF Draft HTTP Message Signatures,
• AWS Signature

a strategy to prevent replay attack ?!?

Api

Don't reinvent the wheel in Authentication, token generating, password storing use the standards.

So, for the topic, which standards for Authentication, token generating, password storing can be used? Can offer some sample implement projects?

Misspelling in README

"sensetive" is spelled incorrectly

why no basic auth?

In "README.md", "簡" should be “简”.

In "README.md", "簡中版" means simplified chinese version, but "簡" is a traditional chinese character, it should be "简".

Security Headers

Hello,

Why is it required to have security headers alike HSTS, CSP and X-FRAME OPTIONS if the API is not browsable?

Rationales

Each thing in the list deserves a file on the rationale behind it, even if those are largely URLs.

Cyber security

Why "User own resource ID should be avoided. Use /me/orders instead of /user/654321/orders." ?

Is that possible can someone explain why the "User own resource ID should be avoided. Use /me/orders instead of /user/654321/orders." is a security concern?

I agree that user can know your 654321 is your user id then probably loop to try /user/654322/orders etc. However, isn't it the api should check whether the user id has privilege as well? E.g. is 654322 customer of the caller's token user? If yes, he can still view it.

So using pk here is just making it easy to loop and test, but by right the code itself should have checking for privilege too.

If not, using UUID would be insecure too right? I can still loop it, but longer period. And if somehow i know other company customer uuid, I can access it too.

Is there any other point I miss out? Thanks!

Serbian translations

Are Serbian translations needed? If so, I'm open to contribute 😄

JWT token should be stored securely if they are used as auth for browser users.

If an application are using JWT in browsers it should be stored securely in a cookie which requires:

• Require SSL on the comunication
• Enable HttpOnly
• Send The Cookie To Only Your Application

Question about "Don't auto-increment IDs. Use UUID instead."

This might seriously cripple database performance since you are suggesting a data type ~68 bytes larger than an integer and which indexes are much more expensive to compute.

What is the motivation behind this rule?

HTTP Headers

This advice:

• Send X-Content-Type-Options: nosniff header.
• Send X-Frame-Options: deny header.
• Send Content-Security-Policy: default-src 'none' header.

Is a bit misguided as they only really have relevance if HTML is returned. If the API returns JSON or raw text there is no way that they can be affected by XFO or CSP.

I can see an argument for XCTO in some circumstances (e.g. SOAP requests).

I'd also include Strict-Transport-Security in the list as that really should be issued by pretty much everything HTTP page.

Should mention CORS

It looks like most of the advice from the OWASP REST Cheat Sheet is discussed in this API-Security-Checklist, but OWASP talks about the importance of CORS, which is not mentioned at all in this API-Security-Checklist. Probably good to make mention. Also, the OWASP REST Cheat Sheet provides a bit more guidance regarding validation that might be good to incorporate.

https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/REST_Security_Cheat_Sheet.md

## Query

Query

Link to pull request with your CodeQL query:

Relevant PR: github/codeql#7286

CVE ID(s)

List the CVE ID(s) associated with this vulnerability. GitHub will automatically link CVE IDs to the GitHub Advisory Database.

• CVE-2021-28169

Report

Describe the vulnerability. Provide any information you think will help GitHub assess the impact your query has on the open source community.

Directly incorporating user input into HTTP requests dispatched from the Java EE RequestDispatcher without proper validation of the input can allow any web application resource such as configuration files and source code to be disclosed.

As stated in the Java API doc, when using a Java EE RequestDispatcher, requests may be dispatched to any part of the web application bypassing both implicit (no direct access to WEB-INF or META-INF) and explicit (defined by the web application) security constraints. Unsanitized user provided data must not be used to construct the path passed to the RequestDispatcher as it is very likely to create a security vulnerability in the application.

This query detects unsafe invocations of RequestDispatcher with user controlled input. Important features include:

• RequestDispatcher constructed from both HTTP request and servlet context
• Path traversal check
• Path encoding check
• Check of path normalization using the java.nio.file.Path package

• Are you planning to discuss this vulnerability submission publicly? (Blog Post, social networks, etc). We would love to have you spread the word about the good work you are doing

Result(s)

Provide at least one useful result found by your query, on some revision of a real project.

• Jetty Utility Servlets ConcatServlet Double Decoding Information Disclosure Vulnerability
• softways-sa/swift-framework
• Online Drug Store

Originally posted by @luchua-bc in github/securitylab#495

Og

Ok

Add a CONTRIBUTING.md file.

See: https://github.com/blog/1184-contributing-guidelines

Due to that this repository is currently trending very successfully, the number and frequency of pull requests to the repository, issues created, discussions, etc, I think adding some formal procedures or guidelines to the repository might be a good idea, to avoid possible future problems, unwanted pull requests (so far, all pull requests look pretty good, but there has been 17 of them already, and the repository is only 3 days old, and so, I think, there's a strong chance of merge conflicts, bad/unwanted pull requests and similar such things occurring at some point in the future). 16 issues created thus far in that 3 days, all legit/good, except for one, which looks a bit spammy (#19); Not sure if formal procedures or guidelines would help at all in that regard, but in any case, it couldn't hurt. Anyhow, figured it might be worth suggesting this. :-)

Expand on the authentication suggestion

Don't use Basic Auth. Use standard authentication instead (e.g., JWT).

This is not very helpful. First of all, "Basic Auth" is "standard" in a way and broadly supported. I would recommend adding a bit more context:

Don't use Basic Auth as the end-user authentication measure. Use OpenID Connect or OAuth 2.0 flow. For server-to-server integrations (M2M), Basic Auth might still work but we recommend extending it with mTLS or VPN.

Translation for korean

I want to translate this repo to korean. How do I do this? Would I send a PR for korean README to you?

Thanks :)

User own resource id should be avoided ?

Hi,

I agree with most rules but I don't understand:

User own resource id should be avoided. Use /me/orders instead of /user/654321/orders

From my perspective. I would prefer use /user/654321/orders than /me/orders. For the latter, at the end, I need to do the lookup in all cases. So I prefer a non ambiguitous uri than "/me/orders". Even if more readable from a human point of view, at a technical one, it can lead to confusion.

So shouldn't it be more

User own resource id should be avoided. Avoid using /me/orders. Better/explicitely use /user/654321/orders instead.

Thanks for the list, will be useful !

More details on token expiration?

I understand this recommendation:

Make token expiration (TTL, RTTL) as short as possible.

Though I wonder what qualifies "as short as possible". If a json web token is used as a session, making that session expire after five minutes is going to make a horrible user experience.

Is there a recommended strategy for short expiration with longer sessions?

Why no word about range, type and length checks?

You should mention range, type and length checks. Peculiarities of JSON/XML parsing should also be mentioned as parser very often work outside of the "safe" realm on most script interpreters, without much failsafe logic. Node notably had an alarming amount of bugs when working with multi-byte encodings.

Websocket handling is another point where most API writers completely disregard such basics. Some try to implement a per byte socket handling, that will eagerly split multibyte chars into impossible bits that can later be used in different "escape" scenarios or be used to attach 3rd party libs.

Why should not use Auto Increment IDs and Use UUIDs instead?

What is the pros and cons for these two identity?

Japanese translations.

We now have two Japanese translations for the checklist, README-ja.md and README-jp.md (just one should be enough, I think).

In terms of the language codes used, README-ja.md is more accurate (jp is the correct country code for Japan, but ja is the correct language code for the Japanese language). However, in terms of the actual translated content, I don't know which of the two would be better, seeing as my understanding of Japanese is very limited.

Perhaps someone who is good with the Japanese language could take a look at the two and send a PR to merge them (from the two files, copy whichever translations are the best, into one single file; delete the remainder)?

Maybe this is something that @arinco or @iogi could take a look at?

Cheers. 👍

Don't recommend JWT

don't use JWT. JWT terrifies me, and it terrifies all the crypto engineers I know. As a security standard, it is a series of own-goals foreseeable even 10 years ago based on the history of crypto standard vulnerabilities. Almost every application I've seen that uses JWT would be better off with simple bearer tokens.

• tptacek on HN post

Also, link to a longer comment from him about why JWT is a bad plan.

"algorithm" in the JWT

It reads,

Don't extract the algorithm from the payload. Force the algorithm in the backend (HS256 or RS256).

Normally, we can find "alg" in the header part, not the payload part of JWT.
Well, what is your point of the risk case?

OAuth referred to as AuthN

This may sound pedantic but I hear it all the time and it leads to confusion about OAuth.
OAuth is not an authentication (AuthN) mechanism, it is an authorization mechanism (AuthZ) which relies on an authorization service or identity provider to confirm the identity of the principal. OIDC might be one mechanism to support this.

Please remove OAuth from the line in authentication section:
"Don't use Basic Auth. Use standard authentication instead (e.g., JWT, OAuth)."

I think there should be a mention about backup plan.

For example,
if your API security has been compromised, what will you do?
- Shutdown your system. (should be the last resort)
- Shutdown only vulnerable service.
- Revoke API Authorization from certain app/people.

Checklist of the most important security countermeasures when designing, testing, and releasing your API.

Since the scope include release phase then it should has topic/bullet that talk about backup plan.

Ways to handle backup plan might not be necessary but at least backup plan topic should be mention in the document somewhere because some backup plan might affect API design or even a whole system structure.

Suggestion: add version information in base file and translation file

This will let translation file easily to spot if it is outdated.

I suggest using this format for version control (V.MAJOR.MINOR.REVISION)
MAJOR = new standard / concept
MINOR = add more checklist
REVISION = correct some typo

for example,
Base file(V1.1.2)
Translation file1(V1.1.1) (Outdated by 0.0.1 version but can be ignored)
Translation file2(V1.1.2) (up to date)
Translation file3(V1.0.1) (Outdated)

Info about version might include in their respective files (let translators handle by themselves), base file or centralize file.

You might as well consider about the changelog. (not necessary though)

Rr

Gjjg

Translation ideas.

Source: Languages used on the Internet -> Content languages for websites (2017.07.16).

Note: Source does not distinguish between dialect variants, regional L10N, etc (for example, with Chinese, I would assume that the statistics includes both simplified and traditional writing variants, or with Portuguese, including both Portugal and Brazil variants alike).

For the purpose of this issue, I'm only listing the top 10 languages mentioned by the source page (there are 38 mentioned by the source list in total, plus a secondary list on the source page; because this issue is only intended to float some general ideas and doesn't concern any concrete goals or plans, being excessive isn't necessary).

Rank	Language	Percentage	Translation Coverage
1	English	51.6%	Original document language.
2	Russian	6.6%	Completed (thanks @tsybenko).
3	Japanese	5.6%	In progress Completed (thanks @arinco and @iogi).
4	German	5.6%	Not translated. Completed (thanks @kloener).
5	Spanish	5.1%	Not translated. Completed (thanks @marc-gr).
6	French	4.1%	Completed (thanks @flibustier and @Sinequanonh).
7	Portuguese	2.6%	Completed (thanks @marcossffilho).
8	Italian	2.3%	Not translated. Completed (thanks @matteocrippa).
9	Chinese	2.0%	Completed (thanks @GrayLand119 and @j-gao).
10	Polish	1.7%	Not translated. Completed (thanks @pilotpirxie).

The purpose of this issue is to suggest possible targets for future language translations, for anyone that might be interested in introducing new translations to the repository. This repository (at this time, currently) is being watched by 205 GitHub users and has 422 forks, and so, maybe this might be useful for someone looking for possible target languages. The logic/rationale here is to hopefully encourage translation of the repository to those languages perceived as being most widely used on the internet (and thus, within the realm of the relevant scope of this repository). Using alternative sources may yield very different results.

Based on the above-mentioned information, these could be good possible target languages for translation at this time:

1. German. (translation added 2017.07.20).
2. Spanish. (translation added 2017.07.17).
3. Italian. (translation added 2017.07.18).
4. Polish. (translation added 2017.11.21).

Also worth mentioning that because this repository is very young and is still a living document, the possibility of data between translations becoming out-of-sync is quite high. There should be no urgency here.