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