Detecting API Discovery Scans for swagger.json: Security Guide

Automated scanning for API documentation is a persistent TTP utilized by attackers to map the attack surface of modern web applications. According to SANS ISC, there is a significant volume of traffic dedicated to identifying swagger.json and other OpenAPI specification files. This reconnaissance activity is often the first step in a larger campaign aimed at discovering unprotected endpoints or flaws in the implementation of RESTful services.

The Evolution from SOAP to RESTful Services

Historically, enterprise applications relied on the Simple Object Access Protocol (SOAP). This protocol offered a high degree of interoperability due to its strict adherence to standards and complex XML schemas. While SOAP provided a structured environment governed by web services, it often led to unnecessary complexity because it failed to leverage the native capabilities of the HTTP protocol.

In contrast, modern developers have shifted toward RESTful architectures. This transition has been driven by the desire for simplicity and speed. However, this shift has introduced a different set of risks. The lack of rigid standards in REST often leads to what security researchers call “vibe coding,” where developers prioritize immediate functionality over careful system design and documentation security. This lack of discipline frequently results in sensitive API definitions being left accessible to the public internet, providing a roadmap for potential exploitation.

Technical Analysis: The Risks of Exposed Documentation

A swagger.json file is essentially a blueprint of an API. It contains comprehensive details about every endpoint, including expected parameters, response formats, and authentication mechanisms. When an attacker finds this file, they no longer need to perform blind brute-force discovery. They can immediately identify administrative routes, deprecated but still active endpoints, and hidden parameters that may be vulnerable to RCE or XSS.

Furthermore, the exposure of these files violates the principles of Zero Trust, as it provides unauthorized users with internal architectural knowledge. If an API endpoint lacks proper Privilege Escalation checks, the information found in a Swagger file allows an attacker to precisely craft requests to exfiltrate data or modify system states.

How to Detect swagger.json Discovery Attempts

To identify these activities, the SOC should monitor web server logs for HTTP 404 and 200 responses targeting specific paths. These typically include /swagger.json, /swagger-ui.html, /v2/api-docs, and /openapi.json. Incorporating these paths into your SIEM rules can help identify the early stages of a reconnaissance-driven APT or automated botnet activity.

Following MITRE ATT&CK framework guidance, this activity maps to the Reconnaissance phase (T1595 - Active Scanning). Attackers use these scans to gather information that will later facilitate more complex attacks, such as Lateral Movement or data exfiltration.

Recommendations for Mitigating API Documentation Exposure

To ensure your environment adheres to RESTful API security best practices, organizations should implement the following controls:

• Environment Segregation: Ensure that API documentation tools like Swagger UI are only enabled in development and staging environments. These tools should never be accessible in a production SOC environment unless protected by strict authentication.
• IP Whitelisting: If documentation must be accessible over the internet, restrict access to specific internal IP ranges or VPN gateways.
• Regular Audits: Use automated tools to scan your public-facing infrastructure for common API documentation filenames. Identifying these exposures before an attacker does is critical for mitigating API documentation exposure.
• Authentication and Authorization: Treat the API documentation itself as a sensitive asset. Require a valid token to view the specification, even if the API endpoints themselves appear to be public.