Skills

noir

Installation
SKILL.md

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

Related skills

More from igbuend/grimbard

Installs
7
Repository
igbuend/grimbard
GitHub Stars
4
First Seen
Feb 19, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn