Spec Analysis
What is Spec Analysis?
When you upload or update an API specification (OpenAPI, Postman Collection, GraphQL, etc.), APIsec automatically reviews it from a security perspective — before any scan runs.
This helps you understand:
- What your API looks like to the platform
- What might be missing from the spec
- What you should configure before scanning
Note: Gaps in the spec are not always vulnerabilities. They often mean APIsec cannot test or understand that part of your API fully. A better spec leads to better testing and more accurate results.
When does it run?
Spec analysis runs automatically when you:
- Register a new application with a spec
- Reload an existing spec
- Onboard from a gateway (Azure, MuleSoft, SwaggerHub, Apigee, etc.)
You will see progress steps like Analyzing API Specification and Generating API Insights during registration.
What does it look for?
1. Spec quality
The platform checks that your spec is valid and readable:
- Is it a proper OpenAPI or Swagger document?
- Are server URLs correct?
- Are there structural issues (for example, broken references)?
If something is wrong, you get a clear error during registration. Fix the spec and try again.
Where to see it: Registration screen, Activity Logs.
2. Sensitive data and risk
APIsec analyzes your spec to identify sensitive endpoints and parameters (for example, fields related to passwords, tokens, or personal data).
Each endpoint gets a sensitivity level: Critical, High, Medium, or Low.
You can also see how many highly sensitive parameters each endpoint has.
Example (same idea as the legacy platform): Sensitive data defined on a GET request (sent in the URL) is risky because URLs can be logged or intercepted. In NG, you spot this by reviewing endpoint method, sensitivity, and parameter details together — not as one fixed sentence in a report.
Where to see it: Application → Endpoints → API Insights.
3. Authentication
The platform reads auth definitions from your spec (security and securitySchemes) and marks each endpoint as:
- Authenticated — requires credentials
- Unauthenticated — open without auth
If auth is not defined in the spec, testing tools cannot tell which endpoints should be protected. That is a configuration gap, not a confirmed vulnerability.
Where to see it: Lock/unlock icon per endpoint in API Insights; Guided Actions if credentials still need to be set up.
4. What to configure next (recommendations)
Instead of a static list of recommendations, APIsec shows Guided Actions — clear next steps based on your app's current state:
| Action | Why it matters |
|---|---|
| Configure Authentication | Enables authenticated security testing |
| Fill in Parameters | Endpoints need values before they can be tested fully |
| Configure RBAC | Tests whether roles and permissions are enforced |
| Set Up BOLA Testing | Tests object-level access controls between users |
| Review Authentication | Shown if an authenticated scan failed — check your credentials |
Each action shows how many endpoints are affected and how much it can improve your coverage.
Where to see it: Guided Actions panel on the application page; App Model coverage ring.
5. Can endpoints actually be tested?
The spec may look fine, but an endpoint might still not be testable (wrong host, missing parameters, unreachable URL).
NG runs reachability and testability checks and marks endpoints as testable or not.
Where to see it: Readiness column in API Insights (GraphQL); endpoint details for REST APIs.
6. Business flows (optional, on demand)
For a deeper view of how your APIs work together, you can run AI Analysis in the API Flows tab. The platform derives real business workflows from your spec (for example, login → create resource → fetch resource).
This is on demand — you start it when you need it, not on every upload.
Where to see it: Application → API Flows → Start AI Analysis.
Where to find everything
| What you want to know | Where to look |
|---|---|
| Endpoint sensitivity and auth status | Endpoints → API Insights |
| Sensitive parameters on an endpoint | Click an endpoint → parameter details |
| What to set up before scanning | Guided Actions panel |
| Overall setup progress | App Model coverage ring |
| Spec upload or parse errors | Registration errors, Activity Logs |
| Bad server URLs in the spec | Warnings during instance creation |
| Postman conversion warnings | Shown when registering from Postman |
| How APIs connect in workflows | API Flows (on-demand analysis) |
Supported formats
- OpenAPI 3.x / Swagger 2.0
- Postman Collections
- GraphQL (introspection / SDL)
- Specs from API gateways (Azure, MuleSoft, SwaggerHub, Apigee, and others)
When you reload a spec, the platform updates endpoints and insights to match the new version.
Why it still matters
Your API specification is the foundation for security testing. The more complete and accurate it is, the better APIsec can:
- Find sensitive data and auth gaps
- Run meaningful scans
- Generate RBAC, BOLA, and business-logic tests
Start with API Insights to see what the platform understood from your spec. Use Guided Actions to finish setup before you trust scan results.