Your First Scan

This page runs through a first scan end to end: pointing Noir at a project, reading what it reports, and shaping the output for your workflow. Each step builds on the one before it, so it's worth following in order the first time through.

Run a Scan

Pick a project directory and scan it:

noir scan /path/to/your/app

Or if you're already inside the project:

noir scan .

Noir reads the source files, detects which frameworks are in use, and prints every endpoint it finds: methods, paths, parameters, headers, and cookies.

v0 compatibility: the v0 form noir -b ./app still works without changes. The router falls back to scan for any invocation that starts with a flag.

Check What Was Detected

Curious which technologies Noir picked up? Add --include techs to see them alongside the results:

noir scan . --include techs

To see every technology Noir knows how to analyze:

noir list techs

If your framework isn't listed, you can still use AI-powered analysis to detect endpoints.

Try Different Output Formats

The default output is a human-readable table. Depending on your workflow, you might want something else:

# Machine-readable JSON for scripting and pipelines
noir scan . -f json

# YAML for easy reading and config-friendly workflows
noir scan . -f yaml

# OpenAPI spec, useful for generating API docs or feeding into tools
noir scan . -f oas3

# cURL commands you can run immediately against a live target
noir scan . -f curl -u https://your-target.com

See all available formats with noir list formats, or in the Output Formats section.

Save Results to a File

Instead of printing to the terminal, write the output to a file with -o:

noir scan . -f json -o results.json

This is useful for diffing results between scans, feeding into CI pipelines, or sharing with your team.

Trace Endpoints Back to Source

Want to know exactly where an endpoint was defined? Add --include path to show source file locations:

noir scan . --include path

Combine multiple enrichments with one flag:

noir scan . --include path,techs -f json -o results.json

Focus Your Scan

Large monorepos may contain many frameworks. You can narrow the scan to what matters:

# Run only the Rails and Django detectors (skip everything else)
noir scan . --only-techs rails,django

# Also run the Rails and Django analyzers (in addition to whatever auto-detection finds)
noir scan . --techs rails,django

# Scan everything except Express
noir scan . --exclude-techs express

# Skip files by glob (useful in monorepos, comma-separated)
noir scan . --exclude-path "*_test.go,vendor/*,**/node_modules/**"

--only-techs and --techs look similar but do different things: --only-techs restricts which tech detectors run (faster scan, only those detectors fire), while --techs adds techs to the analyzer set on top of auto-detection (so their analyzers still run even if detection missed them). Combine both when you want "only these techs, and run them even if undetected".

Enrich the Output

--include adds per-endpoint detail to the plain output, and --ai-context attaches a review context for AI auditors.

# Attach 1-hop handler callees (function/method calls inside the route body)
noir scan . --include callee

# Attach an AI-review-ready context (guards, callees, sources, sinks, validators, signals)
noir scan . --ai-context

# Narrow the AI context to a few categories
noir scan . --ai-context guards,sinks

Derived signals stay linked to their supporting feature buckets. Selecting a signal keeps its supporting evidence, and selecting a feature bucket keeps only the signals linked to that evidence, so filtered exports retain enough context to interpret the finding without adding unrelated signals. The cross-bucket priority roll-up is included when signals are selected explicitly.

See Callee Coverage and AI Context for the data shape and per-framework support.

Quick Reference

Flag	What it does
positional paths	One or more directories to scan (noir scan ./api ./worker)
-b <path>	Same as positional; v0-compatible
-f <format>	Output format (json, yaml, oas3, curl, etc.)
-o <file>	Write output to a file
-u <url>	Base URL prepended to paths; required for --status-codes, --probe, and --probe-via
--include LIST	Enrich plain output with path, techs, callee (comma-separated)
--ai-context [LIST]	Attach AI review context (guards, callee, sources, sinks, validators, signals; or all)
--pvalue TYPE=VAL	Fill parameter values in output (TYPE: any / header / cookie / query / form / json / path)
--only-techs	Run only these tech detectors (skip the rest)
--techs	Add these techs to the analyzer set (in addition to auto-detected ones)
--exclude-techs	Skip these frameworks
--exclude-path	Skip files matching a comma-separated glob list. A pattern with / matches the path from the scan base, one without matches a file or directory name; a matched directory skips everything under it
--status-codes	Probe each endpoint and attach the observed HTTP status code
--exclude-codes	Drop endpoints whose probed status matches (comma-separated; pairs with --status-codes)
-P, --passive-scan	Enable passive security scan
-T, --use-all-taggers	Activate all taggers
--probe	Fire HTTP requests at discovered endpoints (needs -u)
--probe-via <url>	Route probes through this proxy URL
--probe-header VAL	Add a header to each probe (repeatable)
--tls-skip-verify	Skip TLS certificate verification for probe/export/webhook (insecure)
--use-taggers LIST	Activate specific taggers (comma-separated; see noir list taggers)
--export-es <url>	Index endpoints in Elasticsearch
--export-opensearch <url>	Index endpoints in OpenSearch (same wire shape as --export-es)
--export-webhook <url>	POST the endpoint catalog as JSON to a webhook
--ai-provider	AI provider prefix or full URL (see AI Power)
--ai-model NAME	AI model name
--ai-key KEY	AI API key (prefer NOIR_AI_KEY or --ai-key-file PATH: argv is visible in the process list)
--diff-path <path>	Old code path for Diff Mode
--diff-ref <ref>	Git revision to diff against (e.g. main, HEAD~1; see Diff Mode)
--fail-on <list>	Exit 3 when the diff has any of added, removed, changed, auth-removed
--passive-scan-severity LVL	Min passive-scan severity (critical, high, medium, or low; default high)
-d, --debug	Enable debug messages
--config-file <path>	Load default options from a YAML config file
--concurrency <N>	Worker count (default: CPU count, clamped to 4–32; or set NOIR_CONCURRENCY)
--cache-disable	Disable the LLM response cache for this run
--cache-clear	Clear the LLM response cache before running
--strict	Exit with code 2 if any analyzer failed or skipped a file (the scan still reports its results)
--verbose	Detailed logging
--no-log	Suppress all logs
--no-color	Disable ANSI colors in plain output
--no-spinner	Disable loading spinner animations

For build details (Crystal / LLVM / target), run noir version --verbose. Run noir help for the top-level overview or noir help <command> for any command's full flag list.

---

You've completed the Getting Started guide! Here's what to explore next:

• CLI Commands: The full v1 subcommand reference (scan, list, cache, config, rules, and so on)
• Configurations: Set default options so you don't repeat flags every time
• Output Formats: Every output format in detail
• Diff Mode: Compare the attack surface against a path or git revision, and gate CI with --fail-on
• Passive Scan: Scan for security issues like hardcoded secrets and misconfigurations
• AI Power: Use AI to detect endpoints in unsupported frameworks