모든 스캐닝 도구와 PoC 실행은 **BlackArch Linux** Docker 컨테이너 내부에서 실행됩니다. 호스트에는 아무것도 설치되지 않습니다.

---

## 도구

86개의 도구가 카테고리별로 구성되어 있습니다. 각 도구는 지원하는 대상 유형을 명시하며, 오케스트레이터는 호환되지 않는 조합을 자동으로 건너뜁니다.

### 네트워크 및 포트 스캐닝
| 도구 | 설명 |
|------|-------|
| `nmap` | 서비스/버전 탐지를 포함한 전체 포트 스캔 |
| `rustscan` | 빠른 포트 스캐너, nmap에 결과 전달 |
| `masscan` | 고속 TCP/UDP 스캐너 |
| `naabu` | 서비스 탐지가 포함된 포트 스캐너 |
| `netdiscover` | ARP 기반 호스트 탐색 |

### 웹 애플리케이션
| 도구 | 설명 |
|------|-------|
| `nuclei` | 템플릿 기반 취약점 스캐너 |
| `nikto` | 웹 서버 오설정 스캐너 |
| `wapiti` | 블랙박스 웹 취약점 스캐너 |
| `ffuf` | 빠른 웹 퍼저 (디렉토리, 파라미터, 헤더) |
| `feroxbuster` | 재귀적 콘텐츠 검색 |
| `gobuster` | URI/DNS/vhost 무차별 대입 도구 |
| `wfuzz` | 웹 애플리케이션 퍼저 |
| `dalfox` | 파라미터 분석 기능이 포함된 XSS 스캐너 |
| `xsstrike` | 고급 XSS 탐지 엔진 |
| `commix` | 커맨드 인젝션 공격 도구 |
| `sqlmap` | 자동화된 SQL 인젝션 및 탈취 |
| `nosqlmap` | NoSQL 인젝션 스캐너 |
| `httpx` | HTTP 프로빙 및 핑거프린팅 |
| `whatweb` | 웹 기술 핑거프린터 |
| `wafw00f` | WAF 탐지 및 핑거프린팅 |
| `wpscan` | WordPress 취약점 스캐너 |
| `acunetix` | 웹 취약점 스캐너 (API 기반) |
| `arachni` | 웹 애플리케이션 보안 스캐너 |
| `zap` | OWASP ZAP DAST 스캐너 |
| `wapiti` | 블랙박스 취약점 스캐너 |
| `drheader` | HTTP 보안 헤더 분석기 |
| `humble` | HTTP 헤더 보안 점검기 |
| `hakrawler` | URL 및 엔드포인트를 위한 빠른 웹 크롤러 |
| `katana` | 차세대 웹 크롤링 프레임워크 |
| `gau` | 알려진 URL 수집기 (AlienVault, WaybackMachine) |
| `jsluice` | JavaScript 시크릿 및 URL 추출기 |
| `corscanner` | CORS 오설정 스캐너 |
| `crlfuzz` | CRLF 인젝션 스캐너 |
| `smuggler` | HTTP 요청 스머글링 탐지기 |
| `linkfinder` | JavaScript/HTML 소스에서 엔드포인트 탐색 |
| `cariddi` | 시크릿 및 엔드포인트 탐지 기능이 있는 웹 크롤러 |

### API 및 GraphQL
| 도구 | 설명 |
|------|-------|
| `kiterunner` | kite 파일을 사용한 API 라우트 탐색 |
| `graphql_cop` | GraphQL 보안 감사 도구 |
| `restler` | 상태 기반 REST API 퍼저 |
| `apifuzzer` | OpenAPI/Swagger 기반 퍼저 |
| `cherrybomb` | OpenAPI 스펙 보안 린터 |
| `arjun` | HTTP 파라미터 탐색 |
| `paramspider` | wayback/소스에서 파라미터 발굴 |

### DNS 및 정보 수집
| 도구 | 설명 |
|------|-------|
| `amass` | 서브도메인 열거 (패시브 + 액티브) |
| `subfinder` | 빠른 패시브 서브도메인 열거 |
| `dnsx` | DNS 리졸버 및 프로브 도구 모음 |
| `dnsrecon` | DNS 열거 및 존 전송 |
| `fierce` | DNS 정찰 및 호스트 탐색 |
| `theharvester` | OSINT: 이메일, 이름, 호스트, 서브도메인 |
| `puredns` | 와일드카드 필터링이 지원되는 빠른 서브도메인 무차별 대입 도구 |
| `alterx` | 서브도메인 순열 엔진 |
| `waybackurls` | Wayback Machine에서 과거 URL 수집 |
| `httprobe` | 활성 HTTP/HTTPS 호스트 프로버 |

### TLS / SSL
| 도구 | 설명 |
|------|-------|
| `testssl` | TLS 구성 및 암호 스위트 감사 |
| `sslyze` | TLS 스캐너 (암호 스위트, Heartbleed, ROBOT) |
| `sslscan` | SSL/TLS 서비스 스캐너 |
| `tlsx` | 빠른 TLS 프로빙 |
| `tls_attacker` | TLS 프로토콜 공격 도구 |
| `ssh_audit` | SSH 구성 및 알고리즘 감사 도구 |

### SMB 및 네트워크 서비스
| 도구 | 설명 |
|------|-------|
| `smbmap` | SMB 공유 열거 및 권한 확인 |
| `enum4linux` | SMB/NetBIOS 열거 |
| `crackmapexec` | Active Directory 및 SMB 평가 |
| `openvas` | OpenVAS 취약점 스캐너 |

### SAST 및 코드 분석
| 도구 | 설명 |
|------|-------|
| `bandit` | Python SAST — 일반적인 보안 안티패턴 |
| `semgrep` | 커뮤니티 규칙이 포함된 다중 언어 SAST |
| `gosec` | Go 보안 점검기 |
| `bearer` | 개인정보 및 보안 규칙이 포함된 데이터 흐름 SAST |
| `horusec` | 다중 언어 SAST 엔진 |
| `brakeman` | Ruby on Rails SAST 스캐너 |
| `flawfinder` | 일반적인 결함 탐지를 위한 C/C++ 정적 분석 |
| `dependency_check` | OWASP 의존성 취약점 스캐너 |
| `pip_audit` | Python 패키지 취약점 점검기 |

### 소프트웨어 구성 분석(SCA)
| 도구 | 설명 |
|------|-------|
| `osv-scanner` | 오픈소스 취약점 데이터베이스 스캐너 |
| `npm-audit` | Node.js 패키지 취약점 감사 |
| `govulncheck` | Go 모듈 취약점 점검기 |

### 시크릿 탐지
| 도구 | 설명 |
|------|-------|
| `gitleaks` | Git 히스토리 시크릿 스캐너 |
| `trufflehog` | 엔트로피 기반 심층 시크릿 탐지기 |
| `secretfinder` | JS 파일 및 엔드포인트의 시크릿 |
| `detect-secrets` | 베이스라인 기반 시크릿 스캐너 |
| `noseyparker` | 패턴 규칙이 포함된 고속 시크릿 스캐너 |

### IaC 및 구성
| 도구 | 설명 |
|------|-------|
| `checkov` | Terraform/K8s/Dockerfile IaC 스캐너 |
| `tfsec` | Terraform 정적 분석 |
| `terrascan` | 멀티클라우드 IaC 보안 스캐너 |
| `hadolint` | Dockerfile 모범 사례 린터 |

### 클라우드 인프라
| 도구 | 설명 |
|------|-------|
| `prowler` | AWS/GCP/Azure 보안 태세 평가 |
| `kube-bench` | CIS Kubernetes Benchmark 점검기 |

### 컨테이너 및 공급망
| 도구 | 설명 |
|------|-------|
| `trivy` | 컨테이너 이미지 + 파일시스템 취약점 스캐너 |
| `grype` | 컨테이너 및 패키지 취약점 매처 |

---

## 대상 유형 게이팅

오케스트레이터는 각 대상을 하나 이상의 유형으로 분류하고 해당 유형을 지원한다고 선언한 도구만 실행합니다. 이를 통해 예를 들어 웹 URL에 대해 SMB 도구가 실행되는 것 같은 노이즈를 제거합니다.

| 유형 | 예시 | 일치하는 도구 |
|------|---------|-----------------|
| `HOST` | `example.com` | DNS, SSL, 웹, SMB 도구 |
| `IP` | `10.0.0.1` | 네트워크, 포트, SMB 도구 |
| `CIDR` | `10.0.0.0/24` | 네트워크 스캐너 |
| `URL` | `https://app.example.com` | 웹, API, SSL 도구 |
| `PATH` | `/src/myapp` | SAST, SCA, 시크릿, IaC 도구 |
| `REPO` | `https://github.com/org/repo` | 시크릿, SAST, SCA 도구 |
| `IMAGE` | `myapp:latest` | 컨테이너 스캐너 |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | 클라우드 보안 태세 도구 (prowler, kube-bench, terrascan) |

분류는 자동입니다 — 대상 문자열만 전달하면 스캐너가 유형을 식별합니다.

인식되는 클라우드 대상 형식:
- AWS ARN: `arn:aws:iam::123456789012:root`
- 명명된 프로필 축약 표기: `aws:profile=production`
- GCP 프로젝트: `projects/my-project-id`
- Azure 구독 UUID: `00000000-0000-0000-0000-000000000000`

---

## 스캔 모드

| 모드 | 설명 |
|------|-------------|
| `paranoid` | 최대 은밀성 — 패시브 프로빙, 최소 발자국 |
| `passive` | 활성 공격 없음 — 열거 및 배너 그랩만 수행 **(기본값)** |
| `active` | 표준 취약점 점검 활성화 |
| `aggressive` | 전체 스캔: 모든 템플릿, 무차별 대입, 빠른 타이밍 |

---

## 인증 스캔

자격 증명은 적용 가능한 모든 웹 도구(nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx)에 전달됩니다.

### 전역 자격 증명

대상별 재정의가 없는 한 모든 대상에 적용됩니다.

**config를 통해:**```toml
[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

[scan.auth.cookies]
session = "abc123"

[scan.auth.headers]
X-API-Key = "my-api-key"

**CLI를 통해** (전역 전용):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

**해석:** `per-target config > global config`

---

## LLM 분석

API 키가 있으면 LLM 계층이 자동으로 활성화됩니다. 검사 결과에 대해 네 번의 패스를 수행합니다:

| 패스 | 이름 | 수행 작업 |
|------|------|-------------|
| 1 | **트리아지** | 각 발견 항목에 CWE, 신뢰도, 오탐 플래그, 악용 가능성 요약을 할당하고 PoC를 설계합니다 |
| 2 | **PoC 생성** | 컨테이너에 이미 있는 도구를 사용하여 발견 항목을 확인하는 독립형 Python/Bash 스크립트를 작성합니다 |
| 3 | **완화** | PoC 증거를 선택적으로 반영하여 구체적인 단기 완화 조치와 영구 수정 방안을 생성합니다 |
| 4 | **클러스터링** | 근본 원인별로 발견 항목을 그룹화하고 공통 수정 방안을 작성하며 경영진 요약을 생성합니다 |

### 프로바이더 구성

LLM 클라이언트는 OpenAI-API와 호환됩니다 — OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter 및 기타 호환 엔드포인트와 함께 작동합니다.```toml
[llm]
enabled   = "auto"          # "auto" | true | false  (auto = on when api_key present)
api_key   = ""              # or set OPENAI_API_KEY env var
base_url  = ""              # leave empty for OpenAI; set for Ollama/vLLM/etc.
model     = "gpt-4o"        # REQUIRED when LLM is active — no default

# Sampling parameters (all OpenAI-compatible)
temperature = 0.2
top_p       = 0.95
max_tokens  = 4096
# top_k and other non-standard params go in extra_body:
# [llm.extra_body]
# top_k = 40

**vLLM 예제:**```toml
[llm]
base_url = "http://localhost:8000/v1"
api_key  = "token-abc123"
model    = "meta-llama/Meta-Llama-3-8B-Instruct"

**기능 우선순위:** `tool override > category override > global`

### 커스텀 프롬프트

모든 LLM 프롬프트는 재정의할 수 있습니다:```toml
[llm.prompts]
enrich_system    = "You are a senior penetration tester..."
mitigation_user  = "Write remediation steps for: {title}..."
# Available placeholders: {title} {severity} {description} {cwe}
#   {exploitability} {tool} {target} {cves} {raw_output}

---

## PoC 생성 및 실행

### 생성 (항상 호스트 안전)

LLM은 각 발견 항목에 대해 자체 포함된 Python 및/또는 Bash 스크립트를 작성합니다. 스크립트는 BlackArch 이미지에 이미 포함된 도구(`curl`, `sqlmap`, `nuclei`, `dalfox` 등)를 사용하며 `<report>_assets/poc/`에 저장됩니다. 생성 단계는 코드를 실행하지 않으며 파일만 작성합니다.```toml
[llm.poc]
languages        = ["python", "bash"]
only_severities  = ["critical", "high", "medium"]
max_pocs         = 20
allow_git_clone  = false   # permit cloning official exploit PoCs from GitHub

---

## 플러그인 시스템

하나 이상의 `AbstractTool` 하위 클래스를 정의하는 `.py` 파일을 `./plugins/`(또는 `~/.vuln-scanner/plugins/`)에 넣으면 시작 시 자동으로 발견됩니다 — 코드 변경이 필요 없습니다.

**탐지 순서** (이름 충돌 시 나중 항목이 우선합니다):
1. `./plugins/` (CWD 기준)
2. `~/.vuln-scanner/plugins/`
3. `[plugins] dirs` 또는 `--plugin-dir`로 구성된 추가 디렉터리

**예제 플러그인** (`plugins/my_scanner.py`):```python
from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, ScanStatus, TargetType
from vuln_scanner.tools.models import Finding, ScanInput, ScanResult

class MyScannerTool(AbstractTool):
    name: str = "my-scanner"
    category: str = "web"
    # Only runs against URL targets — skipped automatically for IPs, paths, etc.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["my-scanner", "--target", target, "--json"]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        ...

**CLI:**```bash
vuln-scanner --plugin-dir /opt/company-scanners --targets https://app.example.com

구성 수준의 대상별 플러그인 필터는 없습니다 — 해당 논리는 플러그인 자체에 있습니다.

---

## 보고서 형식

세 가지 형식이 병렬로 생성됩니다. 원하는 조합을 선택하세요:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| 단계 | 작업 |
|------|--------|
| 1 | 사전 요구 사항 확인 |
| 2 | `.env` 로드 (없으면 `.env.example`에서 복사) |
| 3 | DefectDojo 스택 시작 |
| 4 | DefectDojo API가 준비될 때까지 대기 |
| 5 | 관리자 자격 증명을 통해 API 토큰 획득 |
| 6 | 취약한 대상 컨테이너 시작 |
| 7 | 각 대상에 연결할 수 있을 때까지 대기 |
| 8 | 스캐너 Docker 이미지 빌드 |
| 9 | 스캐너 실행, 보고서 생성, DefectDojo로 푸시 |
| 10 | URL 및 정리 지침이 포함된 요약 출력 |

**LLM 분석 포함:**```bash
# Copy the example env and add your key
cp .env.example .env
# Edit .env: set OPENAI_API_KEY and VS_LLM_MODEL
./poc.sh

**분해:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

---

## scanner.sh — Docker 래퍼

`scanner.sh`는 스캐너 실행을 위한 권장 일상 인터페이스입니다. `docker compose run`을 감싸므로 compose 호출을 수동으로 입력할 필요 없이 대상과 플래그를 직접 전달하기만 하면 됩니다.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### What it does automatically

- `.env` 로드 (없으면 `.env.example`에서 복사)
- 기존 config가 없으면 `config.example.toml` → `config.toml` 복사
- `vuln_scanner_network` Docker 네트워크가 없으면 생성
- 사용자 지정 `--config` 파일을 컨테이너의 `/app/config.toml`에 마운트
- `--build` 전달 시 이미지 재빌드

---

## 설정

주석이 달린 템플릿을 복사하세요:```bash
cp config.example.toml config.toml

**구성 병합 우선순위:** `CLI > env vars > config.toml > defaults`

---

## 환경 변수

### 핵심

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | 공백으로 구분된 대상 목록 |
| `VS_MODE` | `--mode` | 스캔 모드 |
| `VS_TIMEOUT` | `--timeout` | 도구별 제한 시간(초) |
| `VS_RATE_LIMIT` | `--rate-limit` | 속도 제한(req/s) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | 병렬 도구 슬롯 |
| `VS_INCLUDE_TOOLS` | `--include-tools` | 이름으로 도구 허용 목록 |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | 이름으로 도구 차단 목록 |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | 허용할 카테고리 |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | 차단할 카테고리 |
| `VS_OUTPUT_DIR` | `--output-dir` | 보고서 출력 디렉터리 |

### 보고서

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | 보고서 형식: `markdown html json` |

### LLM

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | API 키(표준 환경 변수, 폴백으로 사용됨) |
| `OPENAI_BASE_URL` | — | 기본 URL 폴백(비 OpenAI 엔드포인트용) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | 모델 이름(활성화 시 필수) |
| `VS_LLM_TEMPERATURE` | — | 샘플링 온도 |
| `VS_LLM_MAX_TOKENS` | — | 최대 출력 토큰 수 |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | 전역 기능 토글(예: `VS_LLM_FEATURE_GENERATE_POC=false`) |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | PoC 실행 활성화(컨테이너 전용) |

### 인증 스캔

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | Bearer 토큰(`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | HTTP Basic 사용자 이름 |
| `VS_AUTH_PASSWORD` | `--auth-pass` | HTTP Basic 비밀번호 |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | 폼 기반 로그인 URL |

쿠키와 추가 헤더는 구성 파일 또는 `--auth-cookie` / `--auth-header` CLI 플래그로 설정해야 합니다.

### 플러그인

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | 플러그인 자동 검색 활성화/비활성화 |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | 추가 플러그인 디렉터리(공백으로 구분) |

### DefectDojo

| 변수 | CLI 플래그 | 설명 |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | DefectDojo 기본 URL |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | API 토큰 |
| `VS_DEFECTDOJO_PRODUCT` | — | 제품 이름 |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | Engagement 이름 |

---

## 프로젝트 구조```
vuln_scanner/
├── config/
│   ├── models.py        # AppConfig, AppLLMConfig, PluginsConfig (pydantic)
│   └── loader.py        # 3-layer merge: TOML + env (VS_*) + CLI
│
├── tools/
│   ├── enums.py         # Severity, Confidence, ScanStatus, ScanMode, TargetType
│   ├── models.py        # Finding, ScanInput, ScanResult, AuthConfig (pydantic)
│   ├── target.py        # classify_target() — maps target string to TargetType set
│   ├── abstract.py      # AbstractTool ABC + subprocess execution helpers
│   ├── __init__.py      # TOOL_REGISTRY (86 tools)
│   └── <tool>.py        # One file per tool (86 total)
│
├── llm/
│   ├── models.py        # LLMConfig, LLMFeatures, PocConfig (pydantic)
│   ├── features.py      # resolve_features() — tool > category > global merge
│   ├── client.py        # LLMClient — thin openai SDK wrapper
│   ├── analyzer.py      # LLMAnalyzer — 4-pass analysis pipeline
│   └── prompts.py       # Default prompt templates (all overridable)
│
├── poc/
│   ├── models.py        # Poc, PocVerdict
│   ├── generator.py     # PocGenerator — writes scripts, never executes (host-safe)
│   └── runner.py        # PocRunner — executes scripts (VS_IN_CONTAINER guard)
│
├── reports/
│   ├── base.py          # AbstractReporter
│   ├── markdown.py      # Professional structured Markdown report
│   ├── html.py          # Self-contained HTML with light/dark theme
│   └── json_reporter.py # Full Assessment JSON dump
│
├── defectdojo/
│   └── client.py        # DefectDojoClient — push findings via REST API
│
├── plugins.py           # Plugin auto-discovery (./plugins/, ~/.vuln-scanner/plugins/)
├── model.py             # Assessment, Cluster, AssessmentStats
└── orchestrator.py      # ScanOrchestrator — type-gated, async concurrent execution

plugins/                 # Drop .py plugin files here (auto-discovered at startup)
main.py                  # Entry point
config.example.toml      # Fully documented configuration template
.env.example             # Environment variable reference
Dockerfile               # BlackArch-based image; bakes VS_IN_CONTAINER=1
docker-compose.yaml                # DefectDojo stack
docker-compose.scanner.yaml        # Scanner service
docker-compose.target.yaml        # Vulnerable test targets (Juice Shop, WebGoat)
scanner.sh                        # Convenience wrapper — runs the scanner via docker compose
poc.sh                            # End-to-end quick-start script (DefectDojo + targets + scanner)

def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
    return ["mytool", "--target", target]

def parse_output(self, raw: str, target: str) -> list[Finding]:
    findings = []
    for line in raw.splitlines():
        if "VULN" in line:
            findings.append(Finding(
                title="Example finding",
                severity=Severity.HIGH,
                description=line,
                tool=self.name,
                target=target,
            ))
    return findings

2. `vuln_scanner/tools/__init__.py`에 등록하세요:```python
from vuln_scanner.tools.mytool import MyTool

TOOL_REGISTRY: dict[str, type[AbstractTool]] = {
    ...
    "mytool": MyTool,
}

**팁:**
- stdout 대신 파일에 쓰는 도구의 경우 `build_command()`에서 `OUTPUT_FILE_SENTINEL`을 사용하고 `self._run_with_tempfile()`을 호출하도록 `run()`을 재정의하세요.
- `applicable_targets = frozenset(TargetType)` (기본값)이 있는 도구는 모든 대상 유형에 대해 실행됩니다. — 진정으로 범용적인 도구에만 사용하세요.
- 바이너리를 찾을 수 없음 → `ScanStatus.SKIPPED` (보고서에서 숨김). 도구 오류 → `ScanStatus.FAILED` (부록 A에 표시).

---

## 개발```bash
# Install with dev dependencies
uv sync

# Run tests (host-safe only — no real tool execution)
uv run pytest tests/ -v

# Lint
uv run ruff check .
uv run ruff format .