igbuend/noir

OWASP Noir - API & Attack Surface Scanner

When to Use Noir

Ideal scenarios:

• API endpoint discovery and inventory
• Attack surface mapping
• Shadow API detection
• Pre-pentest reconnaissance
• API security assessment preparation
• Microservices endpoint cataloging
• REST/GraphQL/WebSocket endpoint discovery
• Framework-specific route analysis

Complements other tools:

• Use before manual penetration testing for endpoint discovery
• Combine with vulnerability scanners (Semgrep, CodeQL) for deeper analysis
• Use with API testing tools (Burp, ZAP) for complete coverage
• Pair with SARIF Issue Reporter for findings analysis

When NOT to Use

Do NOT use this skill for:

• Vulnerability scanning (use Semgrep, CodeQL, or DAST tools)
• Dependency scanning (use OSV-Scanner or Depscan)
• Secrets detection (use Gitleaks)
• IaC analysis (use KICS)
• Runtime API discovery (use API gateways or proxies)

Installation

# Homebrew (macOS/Linux)
brew install noir

# Download binary (Linux)
wget https://github.com/owasp-noir/noir/releases/latest/download/noir-linux-x86_64
chmod +x noir-linux-x86_64
sudo mv noir-linux-x86_64 /usr/local/bin/noir

# Download binary (macOS)
wget https://github.com/owasp-noir/noir/releases/latest/download/noir-macos-arm64
chmod +x noir-macos-arm64
sudo mv noir-macos-arm64 /usr/local/bin/noir

# Build from source (requires Crystal)
git clone https://github.com/owasp-noir/noir.git
cd noir
shards install
shards build --release --no-debug
sudo cp bin/noir /usr/local/bin/

# Docker
docker pull ghcr.io/owasp-noir/noir:latest

# Verify
noir --version

Core Workflow

1. Quick Scan

# Scan current directory
noir

# Scan specific path
noir -b /path/to/source

# Verbose output
noir -b /path/to/source -v

# Quiet mode
noir -b /path/to/source -q

2. Output Formats

# JSON output (default)
noir -b /path/to/source -o endpoints.json

# YAML output
noir -b /path/to/source --format yaml -o endpoints.yaml

# SARIF output
noir -b /path/to/source --format sarif -o results.sarif

# OpenAPI Specification
noir -b /path/to/source --format oas3 -o openapi.json

# HAR (HTTP Archive)
noir -b /path/to/source --format har -o endpoints.har

# Markdown Report
noir -b /path/to/source --format markdown -o report.md

# Plain text
noir -b /path/to/source --format plain

3. Technology-Specific Scanning

# Specify technologies to scan
noir -b /path/to/source -T express,django,spring

# Exclude specific technologies
noir -b /path/to/source --exclude fastapi

# List supported technologies
noir --list-techs

4. Advanced Options

# No color output (for CI)
noir -b /path/to/source --no-color

# Include technical details
noir -b /path/to/source --include-path

# Send results to URL
noir -b /path/to/source --send-req https://api.example.com/endpoints

# Proxy through Burp/ZAP
noir -b /path/to/source --send-proxy http://127.0.0.1:8080

Supported Frameworks

Web Frameworks

| Language | Frameworks | |----------|-----------| | JavaScript/TypeScript | Express.js, NestJS, Koa, Fastify, Hapi | | Python | Django, Flask, FastAPI, Tornado, Bottle | | Java | Spring Boot, JAX-RS, Micronaut, Quarkus | | Ruby | Rails, Sinatra, Grape | | Go | Gin, Echo, Fiber, Chi, Gorilla Mux | | PHP | Laravel, Symfony, Slim, CodeIgniter | | C# | ASP.NET Core, Nancy | | Rust | Actix, Rocket, Axum, Warp | | Kotlin | Ktor, Spring Boot |

API Types

• REST APIs
• GraphQL endpoints
• WebSocket routes
• gRPC services (limited)
• OpenAPI/Swagger definitions

Output Analysis

SARIF Format

# Generate SARIF for integration
noir -b /path/to/source \
  --format sarif \
  -o endpoints.sarif \
  --no-color

# SARIF structure includes:
# - Each endpoint as a "result"
# - HTTP methods (GET, POST, PUT, DELETE, etc.)
# - Route paths
# - Parameters
# - Source file location

JSON Output Structure

{
  "endpoints": [
    {
      "method": "POST",
      "url": "/api/users",
      "params": ["username", "email", "password"],
      "protocol": "http",
      "details": {
        "file": "src/routes/users.js",
        "line": 42,
        "code_type": "javascript"
      }
    }
  ]
}

OpenAPI Output

# Generate OpenAPI spec from discovered endpoints
noir -b /path/to/source --format oas3 -o openapi.json

# Use with API testing tools
swagger-cli validate openapi.json
openapi-generator generate -i openapi.json -g postman-collection

CI/CD Integration (GitHub Actions)

name: Noir API Discovery

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 1'  # Weekly

jobs:
  noir:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Noir
        run: |
          wget -q https://github.com/owasp-noir/noir/releases/latest/download/noir-linux-x86_64
          chmod +x noir-linux-x86_64
          sudo mv noir-linux-x86_64 /usr/local/bin/noir

      - name: Run Noir
        run: |
          noir -b ${{ github.workspace }} \
            --format sarif \
            -o noir-results.sarif \
            --no-color

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: noir-results.sarif
          category: noir-api-discovery

      - name: Generate OpenAPI
        run: |
          noir -b ${{ github.workspace }} \
            --format oas3 \
            -o openapi.json

      - name: Upload Results
        uses: actions/upload-artifact@v4
        with:
          name: noir-results
          path: |
            noir-results.sarif
            openapi.json

Common Use Cases

1. Pre-Pentest Reconnaissance

# Discover all endpoints
noir -b /app/source \
  --format json \
  -o endpoints.json \
  -v

# Generate attack surface report
noir -b /app/source \
  --format markdown \
  -o attack-surface.md

# Create OpenAPI for tools
noir -b /app/source \
  --format oas3 \
  -o openapi.json

2. Microservices Inventory

# Scan multiple services
for service in services/*/; do
  noir -b "$service" \
    --format json \
    -o "inventory/$(basename $service).json"
done

# Combine results
jq -s 'add' inventory/*.json > complete-inventory.json

3. Shadow API Detection

# Scan codebase
noir -b /path/to/source -o discovered-endpoints.json

# Compare with documented API
diff <(jq -r '.endpoints[].url' discovered-endpoints.json | sort) \
     <(jq -r '.paths | keys[]' openapi-spec.json | sort)

# Undocumented endpoints are "shadow APIs"

4. Framework Migration Analysis

# Before migration - discover all routes
noir -b /old/app -T express -o old-endpoints.json

# After migration - verify parity
noir -b /new/app -T fastify -o new-endpoints.json

# Compare
diff <(jq -r '.endpoints[].url' old-endpoints.json | sort) \
     <(jq -r '.endpoints[].url' new-endpoints.json | sort)

Advanced Features

Technology Detection

# Auto-detect technologies
noir -b /path/to/source --list-techs

# Show detected frameworks
noir -b /path/to/source -v | grep "Detected"

Filtering Results

# Only GET endpoints
jq '.endpoints[] | select(.method == "GET")' endpoints.json

# Only authenticated endpoints (heuristic)
jq '.endpoints[] | select(.url | contains("auth") or contains("login"))' endpoints.json

# High-risk endpoints
jq '.endpoints[] | select(.method == "DELETE" or .method == "PUT")' endpoints.json

Proxy Integration

# Send discovered endpoints to Burp Suite
noir -b /path/to/source \
  --send-proxy http://127.0.0.1:8080 \
  --send-req http://target.example.com

# Creates Burp site map automatically

Security Analysis Workflow

Step 1: Discover

noir -b /app/source --format json -o endpoints.json

Step 2: Categorize

# Extract by risk level
jq '.endpoints[] | select(.method == "DELETE")' endpoints.json > high-risk.json
jq '.endpoints[] | select(.params | length > 0)' endpoints.json > with-params.json
jq '.endpoints[] | select(.url | test("/admin|/api/internal"))' endpoints.json > privileged.json

Step 3: Test

# Generate test scripts
jq -r '.endpoints[] | "curl -X \(.method) http://target.com\(.url)"' endpoints.json > test-requests.sh

# Or convert to OpenAPI and use Postman/Newman
noir -b /app/source --format oas3 -o openapi.json

Step 4: Report

# Create comprehensive report
noir -b /app/source --format markdown -o report.md

# Add SARIF for tracking
noir -b /app/source --format sarif -o findings.sarif

Performance Considerations

# Large codebases - use specific technology
noir -b /large/repo -T express -q

# Exclude unnecessary paths
noir -b /repo --exclude "node_modules,vendor,test"

# Minimal output for CI
noir -b /repo -q --format sarif -o results.sarif

Limitations

• Static analysis only: Can't discover runtime-generated routes
• Framework coverage: Limited to supported frameworks
• Dynamic routing: May miss programmatically generated endpoints
• Annotations required: Some frameworks need proper route decorators
• No validation: Doesn't verify if endpoints are accessible
• No authentication: Doesn't detect auth requirements

Rationalizations to Reject

| Shortcut | Why It's Wrong | |----------|----------------| | "Noir found all endpoints = complete coverage" | Dynamic routes, runtime-generated endpoints, and some frameworks may be missed | | "Skip endpoint discovery, review code manually" | Manual review misses endpoints; automated discovery is faster and more complete | | "Only scan main application, skip microservices" | Microservices often expose attack surface; comprehensive scan needed | | "OpenAPI docs are enough" | Documentation often lags code; Noir finds actual implemented endpoints | | "Don't need SARIF output" | SARIF enables integration with security workflows and issue tracking |

References

• Repository: https://github.com/owasp-noir/noir
• Documentation: https://owasp-noir.github.io/noir/
• OWASP Project: https://owasp.org/www-project-noir/
• Supported Technologies: https://owasp-noir.github.io/noir/techs/
• SARIF Output: https://owasp-noir.github.io/noir/usage/output_formats/sarif/