Skip to content

User Guide

Jump to bottom
rawatprince edited this page Aug 26, 2025 · 1 revision

The SpecOps extension interface is organized into several tabs (numbered for convenience) that correspond to a typical workflow. Below is an overview of each tab in order:

  • Specification - Loading an API Specification
  • Servers - Selecting the Target Server & Environment
  • Global Parameters - Managing the Parameter Store
  • Auth Profiles - Configuring Authentication
  • Custom Headers - Adding Extra Headers (Optional)
  • Endpoints Workbench - Crafting & Sending Requests
  • Attack Results - Reviewing Responses

1. Specification - Loading an API Specification

This first tab is used to load your API’s OpenAPI/Swagger definition. At the top, you’ll find buttons for Load from File and Load from URL, as well as a large text area where you can paste the spec JSON/YAML directly.

Loading the Spec

Click Load from File to browse and select an OpenAPI (YAML/JSON) file from disk. Or use Load from URL to fetch the spec from an online endpoint (you’ll be prompted to enter the URL). The raw spec content will be displayed in the text area for review or editing. You can also simply copy-paste the spec into the text area if you have it available.

Note: If your specification’s server URL is defined as a relative path (for example, /v1 or /api), it’s recommended to use Load from URL with a full URL. This way, SpecOps can determine the base host for those relative URLs. If a spec has only a relative server path and no base host is provided, SpecOps won’t know how to build the requests (you’ll see an error about the server URL). Loading from an absolute URL (or including a host in the spec) resolves this.

Parse the Spec

Once the spec text is present, click Parse Specification. SpecOps will parse the content in the background. It supports OpenAPI 3.x natively. If the spec is Swagger 2.0, it will attempt an in-memory conversion to OpenAPI 3 before parsing. The parser will resolve any $ref references, enumerate all paths and operations, and gather parameters. On success, you’ll get a pop-up message indicating the spec was parsed successfully and how many endpoints were found. At this point, the extension’s internal model (SpecOpsContext) is populated with:

  • A list of Endpoints (each is an HTTP method + URL path + operation details from the spec).
  • A Global Parameter Store (all unique parameters across endpoints, including path/query/header/cookie params, and even “virtual” parameters for JSON request body fields like user.name or items[0].id).
  • A list of Server definitions (if any are defined in the spec’s servers array).
  • Any defined Security Schemes (authentication methods) and their requirements (from the spec’s components/securitySchemes).

SpecOps will automatically switch to the next tab (Servers) upon successful parsing, guiding you to continue the setup. (If parsing fails, an error will be logged in the Extender output – common causes are invalid JSON/YAML or unsupported spec features. You can adjust the text and try again.)

Tip: You can re-load or parse a new spec at any time. Doing so will reset the context (clearing out any endpoints/params from a previous spec). The extension will log how many endpoints and unique parameters were loaded for confirmation. Feel free to iterate on your spec and re-import as needed.

2. Servers - Selecting the Target Server & Environment

The Servers tab lets you configure which server/environment from the API spec to target. OpenAPI specs can list multiple server URLs (e.g. production, staging, dev environments, regional endpoints, etc.), and may include template variables in those URLs.

On this tab, you’ll see a dropdown menu of servers defined in the spec. Each entry in the dropdown shows either the server’s description or the base URL. Select the server you want to use for your requests. If the server URL contains variables (e.g. {basePath}, {region}), those will be listed in a table below, where you can supply values.

Server Variables

For each templated variable in the base URL, the table shows a row with the Variable Name, its current Value, the Default value, and any allowed Enum values. Click in the Value cell to change it – if there are enumerated options, you’ll get a dropdown; otherwise, you can type a custom value. The Default comes from the spec, so if you’re okay with it you can leave it as is. The Enum column lists allowed values (if the spec defines them) and is used to populate the dropdown choices. Changing a value here updates the resolved server URL in real time.

Resolved URL Preview

At the bottom of this tab, SpecOps displays the fully resolved server URL after applying the current variable values. This is labeled “Server:” followed by the resolved URL. It updates live as you change variable values, so you can immediately see, for example, https://{region}.api.example.com/{basePath} turn into https://eu.api.example.com/v1 as you fill in the variables. This resolved base URL is what will be prepended to all endpoint paths when making requests.

Iterate Across All Servers

There is a checkbox labeled “Iterate across all servers when sending”. If enabled, SpecOps will consider all server entries when you perform a bulk Ping in the Endpoints tab. In other words, with this option on, the Ping Selected feature will cycle through each server environment for each endpoint you send. This is useful if you want to test every environment (dev, test, prod, etc.) defined in the spec with one action. If you leave it off (the default), only the currently selected server (from the dropdown) is used for requests.

3. Global Parameters - Managing the Parameter Store

The Global Parameters tab is one of the core features of SpecOps. Here you’ll find a table listing every unique parameter discovered in the API specification. This includes all path, query, header, and cookie parameters, as well as “virtual” parameters for JSON request body fields (e.g. a body property like user.name or an array item like items[].id). This global parameter store allows you to set values in one place and have them used consistently across all endpoints that reference those parameters.

This tab contains several key elements:

  • Parameter Table Columns: The table has columns for Name, In (location of the parameter: path/query/header/cookie/body), Value, Type (string/integer/etc.), Required (whether this parameter is required by the API), and Lock (a checkbox). You can click on any Value cell to edit it. If the parameter has defined enum values, the cell will present a dropdown of allowed options; otherwise it’s a free-form text field.
  • Filtering: Above the table is a Filter text box. Typing in this box filters the parameter list in real time, which is useful for quickly finding a parameter by name. (For example, typing “auth” would filter the list to only parameters whose name or location contains “auth”.)
  • Populate from Proxy: This powerful feature scans your Burp Proxy history for a given domain and extracts values that correspond to parameters in the store. For example, if your API spec has a header X-Request-ID and Burp’s proxy history contains X-Request-ID: 12345 for the target host, the extension will set 12345 as the value for that parameter. To use this, click Populate from Proxy, enter the domain of your API (e.g. api.example.com), and SpecOps will update any empty parameters with values found in recent traffic. (Parameters that already have a value or are locked will not be overwritten.)
  • Generate Values: This button helps you fill in dummy data for any parameters that are still empty. Clicking Generate Values opens a menu of options to generate for all empty fields, or only for specific types (Strings, Numbers, Booleans). The value generator uses the parameter name and type to guess a contextually relevant value:
    • If a parameter name contains “email”, it might generate something like user123@example.test.
    • If it detects “date” or “time”, it may insert the current date or a timestamp.
    • It has special handling for common substrings like id, name, phone, zipcode, token, etc., to produce realistic-looking test data (e.g. a GUID for something with “id”, or a JWT-like string for “token”).
    • Numbers might get sample values like 42 or 1001, booleans will get true/false, etc.
  • Import/Export Values: You can export the current parameter values to save or reuse them. Two formats are supported: CSV and JSON.
    • Export to CSV produces a simple file with columns: name, in, value for each parameter.
    • Export to JSON produces a more structured output (including parameter metadata and lock status).
    • Later, you can use Import (CSV or JSON) to bring those values back in. When importing, SpecOps will match the parameters by name+location and apply the values. (It will not overwrite locked parameters on import.)
  • Locking Parameters: Each parameter in the table has a checkbox under the Lock column. Locking a parameter prevents its value from being changed by either Populate from Proxy or Generate Values. This is useful for protecting important values (like an API key or session token you’ve set) from being overwritten by the automation.

4. Auth Profiles - Configuring Authentication

The Auth Profiles tab lists all security schemes defined in the OpenAPI specification and allows you to provide credentials or tokens for each one. This is crucial for testing APIs that require authentication.

On this tab, you’ll see a table with columns: Scheme, Type, In, Name, Scopes, and Value. The Value column is where you enter the actual credential.

Here is how to use this tab:

  • Providing Credentials: For each security scheme listed, click in the Value cell and enter the appropriate credential or token:
    • If the scheme Type is APIKey, enter the API key value itself. SpecOps knows to put this value in the header or query parameter based on the In column.
    • If Type is HTTP and the scheme is "bearer", enter the token string (the extension will add the Bearer prefix automatically).
    • If Type is HTTP and the scheme is "basic", provide the Base64-encoded username:password string for Basic Auth.
    • If Type is APIKey and In is cookie, enter the cookie value.
    • If Type is oauth2 or openIdConnect, enter the access token. SpecOps will treat it similar to a Bearer token.
  • Apply Credentials: After entering your values, click the Apply button to save them into the extension’s context. Once applied, these auth tokens will be used for all subsequent requests that require them.

SpecOps is smart about using these auth profiles. When building a request, it looks at the endpoint’s security requirements (as defined in the spec) and attempts to satisfy them using the tokens you provided.

5. Custom Headers - Adding Extra Headers (Optional)

This tab lets you define rules for adding or modifying HTTP headers on the fly. This is useful for any headers not explicitly part of the API spec (for example, a special testing header, a feature flag, or a correlation ID).

The UI presents a table of Header Rules with columns: Enabled, Header, Value, Scope, Match, and Overwrite. There’s also a master checkbox Apply to Workbench requests at the top - this must be ticked for any custom header rules to be applied.

To create a header rule, click Add and fill in the details:

  • Header: The name of the header to add (e.g. X-My-Header).
  • Value: The static value to set for this header.
  • Scope: This determines when the header is applied. Choose from:
    • ALL - apply to all requests.
    • HOST - apply only to requests to a specific host (provide hostname in the Match column).
    • PATH_PREFIX - apply to requests whose path begins with a certain string (provide prefix in Match).
    • TAG - apply to endpoints that have a given OpenAPI tag (provide tag name in Match).
    • METHOD - apply only to requests with a certain HTTP method (provide method name in Match).
  • Enabled: Ensure this is checked for the rule to be active.
  • Overwrite: If checked, the rule will replace any existing header of the same name. If not checked, the rule will only add the header if it's missing.

Note: SpecOps has guardrails to prevent certain critical headers from being modified by these rules, such as Host, Content-Length, Transfer-Encoding, and Connection, to ensure you don’t accidentally break the request format.

6. Endpoints Workbench - Crafting & Sending Requests

The Endpoints tab is where everything comes together. This workbench provides a list of all endpoints from the spec and tools to interact with them.

Endpoints Table

The top half of the tab contains a table of all endpoints with columns for Method, Path, Summary, and Binding Status. The Binding Status indicates if the request is READY or MISSING_REQUIRED. Ready means all required parameters have a value; Missing Required means some required field is still empty. You can select multiple endpoints using Ctrl+Click or Shift+Click.

Request Preview

The bottom half of the tab shows a Request Preview panel. If you select exactly one endpoint, the preview will display the full HTTP request that SpecOps has built, incorporating the server, parameters, auth, and custom headers. This preview is read-only.

Sending Requests

  • Ping Selected: This button sends requests sequentially for all selected endpoints. A progress bar will appear showing completion percentage, a request counter (e.g. “5 / 12”), and an estimated time to completion (ETA). You can cancel the run at any time. Upon completion, the Attack Results tab will open automatically.
    • Note on Iteration: If the “Iterate across all servers” option is enabled, Ping Selected will send each endpoint on every defined server, so the total number of requests = (number of endpoints) × (number of servers).
  • Send to Repeater / Intruder: You can right-click on any endpoint to send its fully-built HTTP request to Burp Repeater or Intruder for manual testing or fuzzing.

7. Attack Results - Reviewing Responses

After sending requests via Ping Selected, this tab displays the results for you to review.

At the top is a toolbar with a Clear Results button. The main pane is a Results table with columns: Timestamp, Method, Path, Status Code, and Response Length. Each row corresponds to one HTTP request that was sent.

At the bottom, a Request/Response viewer is available. When you select a result row, the panel below will show the exact Request that was sent and the Response that was received.

You can right-click on any result for additional options:

  • View Request/Response - opens a separate, larger window with the request/response.
  • Send to Repeater - sends the same request to a Burp Repeater tab for further manual testing.

Pro Tip: The combination of the Global Parameter Store and Attack Results can be used for rudimentary fuzzing by hand. You can change a parameter’s value, ping an endpoint, then change the value to something else, ping again, and compare the two results in the table.

Typical Workflow Summary

A typical workflow using SpecOps would be:

  1. Load and parse a spec on the Specification tab.
  2. Select the target server (and fill any server variables) on the Servers tab.
  3. Fill in parameter values on the Global Parameters tab (manually, via Generate, or Populate from Proxy). Lock any important values.
  4. Provide auth credentials on the Auth Profiles tab and click Apply.
  5. Optionally, add any custom headers on the Custom Headers tab and enable them.
  6. Go to the Endpoints tab, select one or more endpoints, and click Ping Selected.
  7. Switch to Attack Results to examine the responses. Send any interesting results to Repeater for further manual testing.
  8. If needed, adjust parameter values or other settings and repeat.

Clone this wiki locally