goswagger

GOSWAGGER is a minimal SwaggerHub OSINT scanner written in Go. It searches SwaggerHub APIs for a query, fetches discovered target URLs, and matches each fetched body against regex patterns from regex.yaml.

Background

This project is a Go rewrite created to improve my Go coding skills, and it is totally inspired by the original Python SwaggerSpy project.

Overview

The goal is to make SwaggerHub reconnaissance fast and repeatable for security researchers, developers, and IT teams by combining:

• API discovery from SwaggerHub search results
• configurable regex-based inspection
• minimal, scan-friendly output

Swagger And OpenAPI

Swagger (OpenAPI tooling) is a standard ecosystem for describing REST APIs in JSON or YAML, generating documentation, and improving API integration workflows.

SwaggerHub Context

SwaggerHub is a collaborative API platform built around Swagger/OpenAPI where teams design, version, and publish API definitions.

Why OSINT Matters

Public API responses can accidentally include sensitive values. OSINT scanning helps reduce this risk by:

1. Catching developer oversights early
2. Supporting secure-by-default development habits
3. Reducing chances of credential and token leaks
4. Helping risk and exposure triage
5. Supporting compliance and privacy reviews
6. Creating practical feedback loops for engineering teams

Detection Workflow

GOSWAGGER queries SwaggerHub, collects discovered target URLs, downloads each response, and applies regex patterns to detect potential secrets and credentials.

Install

go install github.com/R0X4R/goswagger@latest

After the first run, goswagger automatically seeds the default regex file at:

~/.config/goswagger/regex.yaml

If the file already exists, goswagger preserves your existing custom regex entries while automatically merging any missing default patterns from newer releases. The regex file may be rewritten when new default patterns are added so the local configuration stays up to date without removing user customizations.

Install from source

git clone https://github.com/R0X4R/goswagger.git && cd goswagger && go install .

Usage

goswagger [flags]

Example:

goswagger -q example.com -t 25

Flags:

Output

Matches are printed in a compact bracketed format:

[HIGH] https://example.com/swagger.json [GITHUB PERSONAL ACCESS TOKEN] [ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]

Regex File Format

regex.yaml uses a structured pattern format with metadata support.

Each pattern entry contains:

• regex → the detection regex
• description → human-readable description
• optional confidence → severity or confidence level

Example:

patterns:

  github_personal_access_token:
    regex: 'ghp_[a-zA-Z0-9]{36}'
    description: GitHub Personal Access Token
    confidence: high

  stripe_live_secret_key:
    regex: 'sk_live_[0-9a-zA-Z]{24}'
    description: Stripe Live Secret Key
    confidence: high

  generic_api_key:
    regex: '(?i)(api[_\-]?key|apikey)[\s]*[:=][\s]*[a-zA-Z0-9_\-]{16,64}'
    description: Generic API Key
    confidence: medium

Pattern Fields

Adding New Regex Patterns

1. Open regex.yaml
2. Add a new entry under patterns:
3. Provide a regex and description
4. Run a scan to validate the pattern

Example:

patterns:

  my_custom_token:
    regex: 'token_[A-Za-z0-9]{24}'
    description: Custom Internal Token
    confidence: medium

Output structure:

[CONFIDENCE] URL [PATTERN NAME] [MATCH]

Notes About Regex Compatibility

• Regexes use Go's regexp engine
• Invalid regex entries are skipped automatically
• YAML strings should usually use single quotes '....'
• Escape backslashes properly when needed

Example:

regex: 'sk_live_[0-9a-zA-Z]{24}'

Not:

regex: "sk_live_[0-9a-zA-Z]{24}"

unless escaping is required.

Recommended Confidence Levels

Examples

Run a scan and print to the terminal:

goswagger -q admin -t 5

Run a scan and save output to a file:

goswagger -q admin -t 5 -o results/output.txt

Limit the crawl to a small number of SwaggerHub pages:

goswagger -q swagger -m 2

Local Test Server

Run the bundled development server for local scanner testing while developing:

go run ./testserver/cmd

Environment variables:

The dev server exposes:

Development Workflow

1. Start the test server in one terminal:

   go run ./testserver/cmd
   

2. Run goswagger against the local server in another terminal:

   goswagger -q testquery -m 2 -b "http://127.0.0.1:8081/apiproxy/specs?sort=BEST_MATCH&order=DESC&query=%s&page=%d&limit=100"
   

3. Edit regex.yaml, pkg/*.go, or the test server, then rerun the same command to verify behavior.

Useful dev modes:

Notes

• Output is intentionally minimal.
• Invalid regex entries are skipped during compilation.
• The tool keeps scanning even if one pattern or one URL fails.

Credits

• Original inspiration: SwaggerSpy by UndeadSec