noir

What this skill does

# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```json
{
  "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

```bash
# 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)

```yaml
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Filtering Results

```bash
# 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

```bash
# 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

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

### Step 2: Categorize

```bash
# Extract by risk level
jq '.endpoints[] | select(.method == "DELETE")' endpoints.json > high-ri