CLI 명령어

v1.0부터 Noir CLI는 동사 기반 구조를 씁니다. 핵심 명령은 scan이고, 나머지는 몇 개의 네임스페이스(list, cache, config, rules)로 묶여 있습니다.

noir <command> [arguments] [flags]

빠른 참조

명령어	설명
noir scan PATHS...	하나 이상의 코드베이스에서 엔드포인트 탐지
noir trace "<METHOD> <URL>"	요청을 라우트·가드·파라미터·싱크로 매핑
noir reach FILE[:LINE]	소스 파일에 닿는 엔드포인트 목록
noir query [FILTERS]	AND 조건 필터로 공격 표면 검색
noir list techs	지원하는 언어, 프레임워크, 분석기 목록
noir list taggers	기본 태거와 프레임워크별 태거 목록
noir list formats	지원하는 출력 형식 목록
noir cache info	LLM 캐시 디렉터리, 항목 수, 크기 표시
noir cache clear	캐시된 AI 응답 전체 삭제
noir cache purge <days>	N일보다 오래된 캐시 항목 삭제
noir config show	현재 사용 중인 설정 파일 출력
noir config edit	$VISUAL / $EDITOR로 설정 파일 열기
noir config init	기본 설정 파일 생성 (여러 번 실행해도 안전)
noir config path	설정 파일 경로 출력
noir rules list	규칙 경로에 설치된 규칙 파일 목록
noir rules update	최신 패시브 스캔 규칙을 clone 또는 pull
noir rules path	설정된 규칙 디렉터리 출력
noir completion zsh	Zsh / Bash / Fish / Elvish 자동완성 스크립트 생성
noir version	버전 출력 (--verbose를 붙이면 빌드 정보 추가)
noir help [command]	전체 도움말 또는 명령어별 도움말

Scan

noir scan은 하나 이상의 코드베이스를 훑으면서 탐지된 기술마다 분석기를 실행합니다. 필요하면 패시브 스캔도 함께 돌리고, 지정한 출력 형식으로 엔드포인트를 출력합니다.

# 단일 코드베이스 스캔
noir scan ./app

# 한 번에 여러 코드베이스 스캔
noir scan ./api ./worker ./jobs

# JSON으로 파일 저장 + 패시브 스캔
noir scan ./app -P -f json -o endpoints.json

# AI 컨텍스트 전체 + plain 출력에 path/techs/callee 포함
noir scan ./app --include path,techs,callee --ai-context

경로를 인자로 바로 넘기든 -b PATH를 반복하든 동작은 같습니다. 스크립트에서 읽기 편한 쪽을 쓰세요.

여러 코드베이스는 나란히 있는 형제 루트로 넘기세요(noir scan ./api ./worker 또는 -b 반복). 이것이 지원하는 모노레포 형태입니다. 중첩되거나 겹치는 루트(예: noir scan /repo /repo/sub)에서는 라우트 정의와 사용처가 서로 다른 루트로 잡힐 수 있어서, 베이스를 넘나드는 경로 prefix를 합치지 않습니다.

Scan 플래그

noir scan -h는 플래그를 아래 섹션으로 나눠 보여줍니다. 섹션마다 자세한 설명이 있는 페이지가 따로 있습니다.

섹션	플래그	자세히
BASE	-b/--base-path, -u/--url	첫 번째 스캔
OUTPUT	-f/--format, -o/--output, --pvalue, --status-codes, --exclude-codes, --exclude-path, --include, --ai-context, --no-color, --no-spinner, --no-log, --strict	출력 형식, AI 컨텍스트 커버리지
PASSIVE SCAN	-P/--passive-scan, --passive-scan-path, --passive-scan-severity, --passive-scan-auto-update, --passive-scan-no-update-check	패시브 스캔
TAGGER	-T/--use-all-taggers, --use-taggers	태거
PROBE	--probe, --probe-via, --probe-header, --probe-match, --probe-skip, --tls-skip-verify	Deliver
EXPORT	--export-es, --export-opensearch, --export-webhook	Deliver
AI Integration	--ai-provider, --ai-model, --ai-key, --ai-key-file, --ai-temperature, --ai-seed, --ai-agent, --ai-agent-max-steps, --ai-dry-run, --ai-include-sensitive, --ai-no-optimize, --ai-native-tools-allowlist, --ai-scope, --ai-max-token, --ai-stream, --ai-max-requests	AI 제공업체, AI 기반 분석
DIFF	--diff-path, --diff-ref, --fail-on	Diff
TECHNOLOGIES	-t/--techs, --only-techs, --exclude-techs	기술 범위 관리
CONFIG	--config-file, --concurrency	설정 파일
CACHE	--cache-disable, --cache-clear	아래 Cache
DEBUG	-d/--debug, --verbose, -h/--help	--verbose는 --include path와 --use-all-taggers도 함께 켭니다

스캔이 성공하면 종료 코드는 0입니다. --strict를 주면 분석기가 실패했거나 파일을 건너뛰었을 때 2로 끝납니다. --fail-on을 주면 diff 스캔에서 지정한 변경 종류가 나왔을 때 3으로 끝납니다. 두 경우 모두 리포트는 먼저 끝까지 씁니다.

v1의 플래그 통합

v0의 일부 플래그 묶음이 v1.0에서 더 짧은 형태로 합쳐졌습니다. 예전 형태도 v1.x 동안에는 경고 없이 그대로 동작합니다.

v1 형식	v0 형식 (계속 동작)
--probe	--send-req
--probe-via URL	--send-proxy URL
--probe-header VAL	--with-headers VAL
--probe-match VAL	--use-matchers VAL
--probe-skip VAL	--use-filters VAL
--export-es URL	--send-es URL
--pvalue query=FOO	--set-pvalue-query FOO
--pvalue header=X	--set-pvalue-header X
--pvalue cookie=X	--set-pvalue-cookie X
--pvalue form=X	--set-pvalue-form X
--pvalue json=X	--set-pvalue-json X
--pvalue path=X	--set-pvalue-path X
--pvalue FOO (TYPE= 없음)	--set-pvalue FOO
--include path,techs,callee	--include-path --include-techs --include-callee
--ai-context guards,sinks	--ai-context (필터 없음, 전체 출력)
noir version --verbose	--build-info
noir completion zsh	--generate-completion zsh
noir list techs	--list-techs
noir list taggers	--list-taggers
noir help	--help-all

v0의 deliver 플래그는 이제 noir scan -h에서 두 섹션으로 나뉩니다. PROBE는 발견한 엔드포인트로 HTTP 요청을 보내고, EXPORT는 엔드포인트 목록을 외부 저장소(Elasticsearch, OpenSearch, webhook)로 보냅니다. 전체 플래그는 다른 도구로 결과 전송하기를, 바뀐 이유와 v1에서 새로 생긴 export는 v0에서 v1로 마이그레이션을 참고하세요.

v1.0에서 제거된 항목

--ollama와 --ollama-model은 여러 릴리스 동안 지원 중단 상태였다가 v1.0에서 제거되었습니다. 대신 --ai-provider ollama [--ai-model NAME]을 쓰세요.

noir scan ./app --ai-provider ollama --ai-model llama3

Trace, Reach, Query

엔드포인트를 나열하는 대신 추적하기 위한 질의 명령 세 개입니다. AI 에이전트(또는 특정 질문을 가진 리뷰어)에게 필요한 형태로, 좁은 질문을 던지면 작은 답을 돌려줍니다. 각 명령은 --ai-context all --include callee가 적용된 스캔을 실행하며 scan의 모든 플래그를 받습니다. --from으로 저장된 리포트를 읽으면 스캔 한 번으로 여러 질문에 답할 수 있습니다.

noir scan ./app -f json --ai-context --include callee -o report.json   # 한 번만

noir trace "POST /api/users/42" --from report.json     # 요청 → 라우트, 가드, 파라미터, 싱크, callee
noir reach src/handlers/users.go:57 --from report.json # 파일 → 그 파일에 선언되거나 호출하는 엔드포인트
noir query --no-guard --sink any --from report.json    # 인증 없이 SQL 싱크에 닿는 라우트

trace는 실제 요청 경로를 선언된 라우트에 대응시킵니다. /api/users/42는 /api/users/{id}, :id, <int:pk>, [id], *에 매칭되고, HEAD 요청은 GET 라우트에 대응됩니다. 매칭되는 라우트를 구체적인 순서로 전부 출력하며 matched_by (exact, pattern, wildcard)를 함께 표시합니다. 전체 엔드포인트 레코드를 출력하고, 매칭이 없으면 가장 가까운 라우트를 candidates로 출력한 뒤 종료 코드 1을 반환합니다.

reach는 FILE을 경로 접미사로 보고 Noir가 기록한 모든 위치(라우트 선언, 핸들러 정의, callee, 가드, 소스, 싱크, 검증기)와 비교해 근거를 via에 나열합니다. 행의 파일이 아닌 곳의 근거에는 경로가 붙습니다. :LINE을 주면 근거를 거리순으로 정렬하고 nearest_line을 채웁니다. Noir는 함수 범위가 아니라 선언 줄만 기록하므로, 줄 번호는 필터가 아니라 정렬 기준입니다. 상속과 동적 로딩은 따라가지 않습니다.

query의 필터는 AND로 결합되고, 한 필터 안의 쉼표 목록은 OR입니다: --method, --url, --path, --handler, --tech, --tag, --param, --param-type, --protocol, --guard / --no-guard, --sink, --source, --signal, --validator (any는 비어 있지 않은 버킷에 매칭). 글롭(*, ?, [)에서 *는 /를 넘어 매칭되고 {id}는 글자 그대로이며, 글롭 문자가 없으면 부분 문자열입니다. --param과 --param-type은 같은 파라미터가 둘 다 만족해야 합니다. rate limiter는 행에서도 --guard에서도 가드로 치지 않으며, 어떤 엔드포인트도 갖지 않은 값을 주면 stderr에 리포트에 있는 값 목록과 함께 알려줍니다.

공통 플래그: --from <report>, -f jsonl|json|text (기본 jsonl), --full(압축 행 대신 엔드포인트 레코드 전체), --limit <n>, --count. 종료 코드는 grep과 같습니다: 0 매칭, 1 매칭 없음, 2 사용법 오류. --from과 함께 스캔 경로나 플래그를 주면 오류입니다(아무것도 스캔하지 않으므로).

압축 행은 엔드포인트 레코드의 투영이며 빈 버킷은 생략됩니다. path:line은 라우트가 선언된 곳(복사본이 병합된 경우 복사본 디렉터리 밖의 첫 파일이며 declarations가 개수를 알려줌), handler는 그 본문이 있는 곳(분석기가 정의 위치를 해석한 경우)입니다:

{"method":"POST","url":"/api/users/{id}","path":"src/routes.go","line":42,"tech":"go_gin",
 "handler":{"name":"updateUser","path":"src/users.go","line":80},
 "params":["id:path","name:json"],"guards":["RequireAuth"],"sinks":["sql"],
 "signals":["idor_review"],"callees":["db.Exec","render"]}

이 명령들과 스캔 한 번 후 --from으로 질의하는 루프, 에이전트가 알아야 할 주의점을 정리한 에이전트 스킬이 skills/noir/SKILL.md에 있습니다. 에이전트의 스킬 디렉터리에 복사해 사용하세요.

List

noir list는 내장 카탈로그를 출력합니다.

noir list techs       # 지원하는 언어, 프레임워크, 스펙
noir list taggers     # 기본 태거와 프레임워크별 태거
noir list formats     # 지원하는 모든 출력 형식
noir list techs -f json   # 기계가 읽는 형식. -f는 text(기본), json, yaml

Cache

noir cache는 디스크에 저장되는 LLM 응답 캐시 (~/.config/noir/cache/ai)를 관리합니다.

noir cache info       # 경로, 항목 수, 총 크기
noir cache clear      # 캐시된 AI 응답 전체 삭제
noir cache purge 30   # 30일보다 오래된 항목 삭제

스캔할 때 쓰는 캐시 옵션은 noir scan에 그대로 있습니다. --cache-disable은 그 실행에서만 캐시를 쓰지 않고, --cache-clear는 스캔 전에 캐시를 비웁니다.

Config

noir config는 사용자 수준의 YAML 설정을 관리합니다.

noir config show      # 현재 설정 파일 출력
noir config edit      # $VISUAL / $EDITOR로 열기
noir config init      # 기본 설정 생성 (여러 번 실행해도 안전)
noir config path      # 최종 경로 출력

설정 디렉터리는 NOIR_HOME이 있으면 그 값을 씁니다. 없으면 Unix에서는 $HOME/.config/noir, Windows에서는 %APPDATA%\noir를 씁니다.

noir config edit는 $VISUAL, $EDITOR, 플랫폼 기본값(Unix는 vi, Windows는 notepad) 순서로 에디터를 고릅니다. 설정 파일이 아직 없으면 먼저 만든 뒤 엽니다.

기본 파일이 아닌 다른 설정 파일을 쓰려면 show, edit, path에 --config-file PATH를 넘기세요.

noir config show --config-file ./ci/noir.yaml   # 특정 파일 출력
noir config path --config-file ./ci/noir.yaml   # 절대 경로 해석

init은 항상 기본 파일을 만들고 --config-file은 무시합니다.

Rules

noir rules는 패시브 스캔 규칙 저장소를 관리합니다.

noir rules list       # 설치된 규칙 파일 목록
noir rules update     # 최신 규칙을 clone 또는 pull
noir rules path       # 규칙 디렉터리 출력

기본 규칙 경로는 ~/.config/noir/passive_rules입니다. NOIR_HOME으로 바꾸거나, 스캔할 때 --passive-scan-path PATH로 다른 경로를 지정할 수 있습니다.

Completion

noir completion <shell>은 지정한 셸의 자동완성 스크립트를 출력합니다.

noir completion zsh    > "${fpath[1]}/_noir"
mkdir -p ~/.local/share/bash-completion/completions
noir completion bash   > ~/.local/share/bash-completion/completions/noir
mkdir -p ~/.config/fish/completions
noir completion fish   > ~/.config/fish/completions/noir.fish
mkdir -p ~/.config/elvish/lib
noir completion elvish > ~/.config/elvish/lib/noir.elv  # 그 다음 rc.elv에서 `use noir`

스크립트는 모든 서브커맨드를 알고 있습니다. noir <TAB>은 동사 목록을, noir scan -<TAB>은 scan 플래그를 완성합니다. Elvish 스크립트는 $edit:completion:arg-completer[noir]에 완성기를 등록합니다. 셸별 설정 방법은 셸 자동완성을 참고하세요.

Version

noir version은 버전 번호만 출력합니다. noir version --verbose는 Crystal, LLVM, 타깃 트리플 같은 빌드 정보를 함께 보여줍니다(v0의 --build-info와 같은 내용).

Help

noir help는 전체 개요를, noir help <command>는 해당 명령어의 플래그를 보여줍니다.

글로벌 플래그

다음 플래그는 scan뿐 아니라 모든 서브커맨드에서 동작합니다.

플래그	효과
--no-color	모든 명령의 출력에서 ANSI 색상 제거 (NO_COLOR 환경 변수도 인식)
--no-spinner	로그는 그대로 두고 로딩 스피너만 끔
-v, -V, --version	Noir 버전을 출력하고 종료
-h, --help	현재 명령의 도움말 표시

--no-color와 --no-spinner는 동사 앞뒤 어디에 두어도 됩니다. noir --no-color list techs와 noir list techs --no-color는 같은 명령입니다. -v/--version은 동사 앞에서만 동작합니다. 동사 뒤에서는 noir version을 쓰세요(noir rules update -v의 -v는 verbose입니다).

명령어별 플래그(출력 형식, 동시성, 패시브 스캔, AI 제공업체 등)는 noir scan에 있습니다. 전체 목록은 noir help scan으로 볼 수 있습니다.

v0 호환성

v0의 호출 방식은 v1.x에서 수정 없이 그대로 동작합니다.

# 세 형태 모두 같은 스캔 결과를 냅니다
noir -b ./app                # v0 형식 (scan으로 라우팅)
noir scan ./app              # v1 형식
noir scan -b ./app           # v1 동사 + v0 스타일 플래그

글로벌 플래그를 뺀 첫 인자가 알려진 동사가 아니면 Noir는 scan을 실행합니다. CI 파이프라인, GitHub Actions, Dockerfile entrypoint, 셸 alias를 고치지 않아도 됩니다.

지원 중단 경고는 이후 v1.x 릴리스에서 추가됩니다. 동사 형식이 필수가 되는 것은 v2.x부터입니다.