Is it appropriate to secure/hide Swagger/OpenAPI Specification documentation?

user_1720077 0
Viewed 1180

I have been having a philosophical debate with some of my team around the idea of hiding our Swagger/OAS API documentation in order to increase application security.

There are basically two schools of thought: 1. publish the documentation for consumption by anyone or 2. allow only authenticated/authorized users access to the documentation.

Neither of these approaches would impact the real strength of our API authentication/authorization methods - they would still be enforced on each API call.

The main crux of the argument is that having the API methods documented would give bad actors a leg up on breaking into our systems. I feel like that's a pretty low bar.

However, I am curious if there's any general security practices or guidance in this area.

swagger api-design security
1 Answers

First:

Security trades off everything

Example: Dev Ops is impossible if security is your first priority without having a risk driven approach.

If you trust your developers and give them access to your production system without any auditing and two factor workflows, you will run into security issues.

Second:

You have to analyse your risks. Risk is a two dimensional value of probability and impact and if the risk is too high, you have to take action in order to reduce the risk.

Example: How likely is it, that someone hacks your API and what is the impact?

Lets say, that the impact is very high and the probability is very low.

Following this matrix you have a moderate risk. enter image description here

If your PO is not willing to take that risk you have to take some action to reduce it.

One idea could be to hide the API spec, but that would only reduce the probability of that risk right? And the probability is already very low. So, this doesn't reduce the risk anymore.

Hence, you have to reduce the impact. Well, that depends on why the impact is so high, right?

On the other hand: Suppose you guess that the scenario that "someone hacking your api" has a moderate probability when the spec and the api is GA.

Then hiding the spec could reduce the probability a little. May from moderate to low. This would reduce your risk from High risk to a Moderate risk.

Conclusion: Hiding the api spec is an action that reduces the probability that someone gets access to your api without having the permission.

If the probability is already very low, there is no need to hide the api spec regarding security concerns. There may be other reasons to hide the spec.

Table taken from Impact_and_Probability_in_Risk_Assessment

user_8188320
Related