이것은 `seclab-taskflow-agent`와 `seclab-taskflows`(상위)를
전이적으로 가져오므로,
`seclab_taskflows.taskflows.audit.*`,
`seclab_taskflows.toolboxes.local_file_viewer`,
`seclab_taskflows.toolboxes.gh_file_viewer`, 그리고
`seclab_taskflows.configs.model_config` 형태의 모든 점 표기 참조가
런타임에 상위 배포판에서 해석됩니다.

---

## 목차

1. [이것은 무엇인가](#what-this-is)
2. [빠른 시작](#quick-start)
3. [아키텍처](#architecture)
4. [파이프라인, 단계별로](#the-pipeline-stage-by-stage)
5. [커버리지 피드백 루프](#the-coverage-feedback-loop)
6. [구조 인식 퍼징](#structure-aware-fuzzing)
7. [반복과 캠페인 전반에 걸친 영구 코퍼스](#persistent-corpus-across-iterations-and-campaigns)
8. [트리아지 및 취약점 보고서](#triage-and-vulnerability-reports)
9. [라이브 대시보드](#live-dashboard)
10. [출력 파일](#output-files)
11. [데이터베이스 스키마](#database-schema)
12. [MCP 도구 (에이전트의 어휘)](#mcp-tools-the-agents-vocabulary)
13. [조정 가능한 노브 (환경 변수)](#tunable-knobs-environment-variables)
14. [파이프라인 확장](#extending-the-pipeline)
15. [벤치마크 프로젝트와 결과](#benchmark-projects-and-results)
16. [제한 사항과 주의점](#limitations-and-gotchas)
17. [보안 경고](#security-warning)
18. [개발: 테스트, 린팅, 기여](#development-testing-linting-contributing)
19. [용어집](#glossary)

---

## 이것은 무엇인가

이 태스크플로는 완전 자율 퍼징 파이프라인입니다. 네이티브 C/C++ 프로젝트의
GitHub 저장소가 주어지면 다음을 수행합니다:

1. AFL++ + clang/llvm/lcov + ctags/cscope/graphviz가 없으면 설치하고,
2. 소스를 가져오고,
3. 후보 퍼즈 대상(파서, 디코더, 검증기 등)을 식별하고,
4. 빌드 시스템을 분석하고,
5. 대상당 하나 이상의 하네스 후보를 작성하고, 각각을
   AFL 계측 `.afl` 바이너리와 커버리지 계측 `.cov` 바이너리로 모두 빌드하고,
6. (선택적으로) 60초 커버리지로 후보를 검증하고 최선의 것을 유지하고,
7. 시간 예산을 두 배로 늘려가며 퍼즈/커버리지/개선 루프를 실행하고,
8. 모든 크래시를 트리아지하고, 이전에 알려진 크래시가 여전히 재현되는지 확인하고,
   판정, 익스플로잇 가능성, 제안 패치, 회귀 테스트 스케치를 포함한
   크래시별 마크다운 취약점 보고서를 작성하고,
9. 다음 캠페인을 위한 Fuzz-Introspector 스타일 호출 그래프 + 미접촉 API 보고서를
   작성하고,
10. 모든 것을 라이브 HTML 대시보드에 게시합니다.

이 파이프라인은 정신적으로 **OSS-Fuzz 스타일**입니다: 동일한 기법 중 상당수
(포맷별 뮤테이터와 사전, 구조 인식 토큰 스플라이싱, 커버리지 기반 하네스 개선,
기계 판독 가능 보고서, 중복 제거된 스택 해시 크래시)를 사용하지만,
훨씬 더 작고 자체 완결적입니다.

---

## 빠른 시작```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

---

## 아키텍처

세 개의 계층, 위에서 아래로:```
┌────────────────────────────────────────────────────────────────────┐
│  scripts/fuzzing/run_fuzzing.sh                                    │
│      shell driver; chains the taskflow stages with `set +e`        │
└────────────────────┬───────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/taskflows/fuzzing/*.yaml                     │
│      LLM agent prompts; one YAML per pipeline stage                │
└────────────────────┬───────────────────────────────────────────────┘
                     │  (calls MCP tools)
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/mcp_servers/                                 │
│   ├ fuzz_context.py    persistence (SQLite via SQLAlchemy)         │
│   └ fuzz_runner.py     subprocess wrappers (AFL, clang, lcov, ...) │
│                                                                    │
│  scripts/fuzzing/dashboard.py                                      │
│   read-only HTML view of fuzz_context.db                           │
└────────────────────────────────────────────────────────────────────┘

반복마다, 각 하네스에 대해 에이전트는 다음을 수행한다:

1. 이 하네스의 안정적인 코퍼스 디렉터리를 얻기 위해 `get_persistent_corpus_dir(harness_id)`를 호출한다.
2. `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>, output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`를 호출한다.
3. LCOV 트레이스파일과 HTML 리포트를 생성하기 위해 `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue, output_dir=<run>/coverage)`를 호출한다.
4. `coverage_report` 행과 미커버 항목별 `coverage_gap` 행을 영속화하기 위해 `store_coverage_from_lcov(run_id, lcov_path, html_path)`를 호출한다.
5. AFL의 반복 큐를 영속 코퍼스에 병합하고 크기를 제한적으로 유지하기 위해 `cmin`을 실행하는 `fold_queue_into_persistent_corpus(...)`를 호출한다.
6. `get_coverage_summary` + `get_coverage_gaps`를 읽은 뒤, 다음 중 하나를 수행한다:
   - 미커버 분기에 도달하기 위해 (`coverage_feedback`으로 태그된) 새 시드를 추가하거나,
   - 추가 API를 호출하도록 하네스 소스를 편집하거나,
   - AFL이 가드를 만족시키는 데 필요한 매직 상수에 대한 사전 항목을 자동 추가하기 위해 `enrich_dictionary_from_uncovered(...)`를 호출하거나,
   - 해당 갭을 건너뛴다 (콜드 에러 경로 / 벤더 코드).
7. 대시보드의 반복 타임라인이 무엇이 변경되었는지 추적할 수 있도록 `store_iteration_note(repo, iteration_number, harness_id, note=<one line summary>)`를 호출한다.

**정체 감지.** 두 번의 연속 반복이 모두 라인 커버리지의 절대 퍼센트 포인트 기준으로 `FUZZ_PLATEAU_THRESHOLD_PCT`(기본값 `1.0`) 미만의 증가에 그치면 루프는 조기 종료된다.

---

## 구조 인식 퍼징

세 가지 상호 보완적인 메커니즘이 원시 바이트 변이보다 더 강력한 입력을 생성한다.

### 1. 포맷별 사전 + 커스텀 뮤테이터

`input_kind`가 알려진 포맷과 일치하는 타깃의 경우, taskflow는 미리 만들어진 사전과 `LLVMFuzzerCustomMutator` C 소스 파일을 제공한다:

| 포맷 | 사전 | 뮤테이터 | 비고 |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | 토큰 스플라이스, 균형 잡힌 괄호 복제/삭제, 타입 뒤집기 |
| `xml` | `xml.dict` | `xml_mutator.c` | 태그, 엔티티, DTD, billion-laughs 토큰 |
| `regex` | `regex.dict` | `regex_mutator.c` | 앵커, 클래스, 수량자, 실제 ReDoS 패턴 |
| `binary_tlv` | _(없음)_ | `binary_tlv_mutator.c` | 길이 접두사 레코드: 길이 오버플로 / 복제 / 삭제 |
| `png` | `png.dict` | _(binary_tlv 재사용)_ | PNG 사전 + binary_tlv 뮤테이터 |

이들은 `write_initial_harnesses`(사전이 시드 옆에 복사됨)와 `build_harnesses`(뮤테이터가 AFL 바이너리에 링크됨)에 의해 자동으로 선택된다. 각 뮤테이터는 변이의 50%를 AFL의 기본 바이트 뮤테이터에 위임하므로 엔진의 무작위성을 잃지 않는다.

새 포맷을 추가하려면: `<name>.dict` 및/또는 `<name>_mutator.c`를 `src/seclab_taskflows/dictionaries/`에 넣은 다음, `fuzz_runner.py` 하단의 `_FORMAT_ASSETS` 맵에 등록한다.

### 2. 소스 인식 (프로젝트별) 스마트 뮤테이터

익숙하지 않은 포맷이거나 더 강력한 프로젝트별 토큰을 원할 때마다, `generate_smart_mutator`는 타깃 저장소의 자체 `.c`/`.h` 파일을 스캔하여 스플라이스 사전이 다음에서 추출된 `LLVMFuzzerCustomMutator` C 파일을 생성한다:

- 알파벳 문자가 3개 이상인 문자열 리터럴 (컴파일러/라이선스 노이즈, 경로, 헤더, asm 제약, 포맷 지정자를 필터링한 후),
- `#define`, `case`, `enum`에서 가져온 32비트 숫자 상수 (0, 1, 256, 0xff… 같은 일반적인 작은 정수 노이즈를 필터링한 후).

세 가지 포커스를 사용할 수 있다:

| 포커스 | 스플라이스 대상 | 사용 시기 |
|-------|-----------------|-------------|
| `strings` | 프로젝트 문자열 리터럴만 | 텍스트 포맷 (JSON, XML, YAML, CSV) |
| `constants` | 32비트 숫자 매직 값만 | 바이너리 프로토콜, 매직 넘버가 있는 헤더 |
| `combined` | 둘 다 | 기본값; 보통 가장 좋음 |

`generate_smart_mutators(...)`(복수형)를 `HARNESS_CANDIDATES >= 3`과 함께 사용하면 각 포커스가 예선 라운드에서 후보 하네스가 된다.

### 3. 프로젝트 인식 AFL 사전 + 커버리지 기반 강화

캠페인이 진행됨에 따라 AFL `-x` 사전을 구축하고 확장하는 두 가지 상호 보완적인 도구가 있다:

- **`generate_project_dictionary(source_root, output_path)`** — 반복 1 이전에 한 번 실행되며, 스마트 뮤테이터가 사용하는 것과 동일한 소스 토큰 집합을 정적으로 추출하여 AFL 사전으로 기록한다. 숫자 상수는 양쪽 엔디언으로 모두 출력되므로, 퍼저는 호스트 바이트 순서에 관계없이 `memcmp(x, &magic, 4)`를 만족시킬 수 있다.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path, uncovered_locations)`** — 매 반복의 커버리지 단계 이후에 실행되며, 미커버 라인 근처의 조건부 가드(`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`)를 주변 소스에서 스캔하고, 새로운 토큰이 있으면 사전에 추가한다. 멱등적이다: 이미 존재하는 항목은 다시 추가하지 않는다.

### 4. 코퍼스 스플라이스 연산

`corpus_dir`이 `generate_smart_mutator`에 전달되면, 생성된 C는 코퍼스 스플라이스 연산자도 갖게 된다: 첫 호출 시 해당 디렉터리에서 최대 64개 파일을 로드하고(각 4 KiB로 제한), 그 이후로는 해당 파일의 임의 하위 영역을 변이된 입력에 스플라이스할 수 있다. 이는 AFL의 기본 havoc이 잘 수행하지 못하는 재조합 스타일 연산자를 뮤테이터에 제공한다. `get_persistent_corpus_dir(...)`와 함께 사용하면 스플라이스 라이브러리가 "AFL이 이미 발견한 것을 리믹스"하게 된다.

---

## 반복 및 캠페인 전반에 걸친 영속 코퍼스

각 하네스는 다음 위치에 안정적인 코퍼스 디렉터리를 가진다:```
<workspace>/corpus/harness_<id>/

---

## 출력 파일

모두 `~/.local/share/seclab-taskflow-agent/seclab-taskflows/` 아래에 있습니다.

| 경로 | 내용 |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — 타깃, 하네스, 실행, 커버리지, 크래시, 판정, 호출 그래프, 하네스 제안, 반복 노트 |
| `fuzz_runner/builds/` | 빌드된 `.afl` 및 `.cov` 바이너리 |
| `fuzz_runner/runs/` | AFL 출력 디렉터리 + LCOV 파일 + HTML 커버리지 리포트 |
| `fuzz_runner/corpus/harness_<id>/` | 하네스별 영구 코퍼스 (반복 및 캠페인 전반에 걸쳐 유지됨) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Markdown 캠페인 요약, 판정별로 그룹화된 크래시 |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | 크래시별 Markdown 취약점 리포트 |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | 정적 호출 그래프 + 도달/미도달 오버레이 |

---

## 데이터베이스 스키마

`fuzz_context.db`의 테이블 (SQLAlchemy를 통한 SQLite):

| 테이블 | 주요 컬럼 |
|-------|--------------------|
| `fuzz_target` | `repo, file, function, signature, input_kind` |
| `harness` | `target_id, repo, harness_path, afl_binary_path, cov_binary_path, build_status, version, sanitizers` |
| `seed_corpus` | `target_id, source, path, bytes_count, added_in_iteration` |
| `fuzz_run` | `harness_id, iteration_number, exec_per_sec, paths_total, crashes_count, status, output_dir, started_at, ended_at` |
| `coverage_report` | `run_id, lines_total, lines_hit, line_pct, fns_*, branches_*, lcov_path, html_path` |
| `coverage_gap` | `report_id, file, function, line, kind, reason_hint` |
| `crash` | `run_id, input_blob_path, minimized_path, stack_top_hash, sanitizer_output, verdict, bug_class, cwe, severity, vuln_report_path, reproducer_path, classification, notes` |
| `call_graph` | `repo, target_id, dot_path, svg_path, functions_total, functions_in_graph, functions_reached, functions_unreached, untouched_surface_json` |
| `harness_suggestion` | `repo, function_name, file, rationale, input_kind, priority` |
| `iteration_note` | `repo, harness_id, iteration_number, note, created_at` |

스키마 마이그레이션은 `fuzz_context.py`의 `_migrate()`에 있습니다. 새 TABLE은
`Base.metadata.create_all()`에 의해 자동 생성되며, 새 COLUMN만
PRAGMA 기반 `ALTER TABLE`이 필요합니다.

---

## MCP 도구 (에이전트의 어휘)

에이전트는 AFL이나 clang을 직접 호출하지 않습니다 — MCP 도구를
호출하여 파이프라인을 구성합니다. 용도별로 그룹화된 전체 목록:

### 영속성 (`fuzz_context.py`)

- `store_fuzz_target`, `get_fuzz_targets`
- `store_harness`, `update_harness_build`, `get_harnesses`
- `store_seed`, `start_fuzz_run`, `finish_fuzz_run`, `get_fuzz_runs`
- `store_coverage_from_lcov`, `get_coverage_summary`, `get_coverage_gaps`,
  `coverage_plateau_reached`
- `store_crash`, `update_crash_verdict`, `get_crashes`,
  `get_crashes_grouped`, `suggest_severity`
- `store_call_graph`, `get_call_graphs`, `get_repo_reached_functions`
- `store_harness_suggestion`, `get_harness_suggestions`
- `store_iteration_note`, `get_iteration_notes`

### 빌드 / 퍼징 / 커버리지 (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — `.afl` 및 `.cov` 바이너리를 빌드합니다
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — `.cov` 바이너리에 대해 AFL 큐를 재생하고 LCOV를 내보냅니다
- `extract_dictionary` — 바이너리에서 출력 가능한 문자열을 추출합니다
- `package_reproducer` — 단일 크래시 `.tgz`를 묶습니다

### 영구 코퍼스 (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### 포맷 자산 (C5)

- `list_format_assets`, `get_format_dictionary`, `write_format_mutator`

### 스마트 뮤테이터 + 프로젝트 인식 사전

- `generate_smart_mutator`, `generate_smart_mutators`
- `generate_project_dictionary`, `enrich_dictionary_from_uncovered`

도구 함수는 `@mcp.tool()` (FastMCP)로 데코레이트됩니다. 테스트 내에서는
`.fn` 속성을 통해 호출합니다. 예:
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## 조정 가능한 설정 (환경 변수)

| 변수 | 기본값 | 목적 |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | 타깃당 작성되는 후보 하네스 수. OSS-Fuzz-Gen 스타일 경쟁을 위해 2 또는 3으로 설정합니다. 검증 단계에서 각 후보를 `QUALIFIER_SECONDS` 동안 실행하고 라인 % 기준으로 최고를 유지합니다. |
| `QUALIFIER_SECONDS` | `60` | 검증 단계에서 후보당 실시간 예산. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | 두 연속 반복이 정체로 간주되어 루프가 조기 중단되는 라인 커버리지 증가량 (절대 pp). |
| `FUZZ_DASHBOARD_PORT` | `8765` | 라이브 대시보드 포트. |
| `FUZZ_NO_DASHBOARD` | (미설정) | 대시보드 시작을 건너뛰려면 `1`로 설정합니다. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | `fuzz_runner`의 도구별 서브프로세스 타임아웃 (초). |
| `LOCAL_SHELL_TIMEOUT` | `180` | `local_shell`의 명령별 타임아웃 (초). |

표준 에이전트 변수 (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …)도 포함됩니다. 전체 목록은 프로젝트 루트 README를 참조하세요.

---

## 파이프라인 확장

### 새 포맷 추가 (뮤테이터 + 사전)

1. `dictionaries/<name>.dict` (AFL `-x` 포맷) 및/또는
   `dictionaries/<name>_mutator.c` (libFuzzer 커스텀 뮤테이터)를 추가합니다.
2. `fuzz_runner.py` 하단의 `_FORMAT_ASSETS`에 등록합니다:   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

코드베이스 규칙 (이 규칙들의 캠페인 이력 버전은 `benchmark/improvements.md`도 참조):

- `os.environ.get(NAME, "default")` 대신 `os.environ.get(NAME) or "default"`를 사용하세요. 그렇지 않으면 YAML 템플릿 치환으로 인한 빈 문자열이 반환될 수 있습니다.
- 새 애노테이션에는 `Optional[X]`가 아닌 `X | None` (PEP 604)을 사용하세요.
- 테스트는 데코레이트된 이름이 아니라 `.fn(...)`을 통해 MCP 도구를 호출합니다.
- 테스트에서 `/tmp/...` 리터럴을 피하세요 — `tmp_path` pytest 픽스처를 사용하세요 (lint 규칙 `S108`).
- 테스트 메서드 내부의 모든 인라인 임포트는 파일 상단으로 옮길 수 없는 경우 (예: `pytest.skip` 이후 조건부로 임포트되는 경우) `# noqa: PLC0415`가 필요합니다.
- 복합 진리 테스트의 경우 한 줄에 하나의 단언만 사용하세요 (lint 규칙 `PT018`).

개선 사항 추적기(`benchmark/improvements.md`)는 버전 전반에 걸쳐 파이프라인에 추가된 내용을 지속적으로 기록하는 로그입니다. 실질적인 기능을 추가할 때는 변경된 내용, 위치, 그리고 이를 보호하는 테스트를 설명하는 섹션을 그곳에 추가하세요.

---

## 용어집

- **AFL++** — 커버리지 기반 그레이박스 퍼저; 여기서의 실행 엔진입니다.
- **libAFLDriver** — AFL++ 하네스가 libFuzzer 진입점 규약(`LLVMFuzzerTestOneInput`)을 사용할 수 있게 해주는 정적 라이브러리입니다.
- **LCOV** — 업계 표준 커버리지 트레이스파일 형식입니다. 우리는 `llvm-cov export -format=lcov`를 통해 내보내고 직접 파싱합니다.
- **`stack_top_hash`** — ASan/UBSan 스택 트레이스의 상위 N개 정규화된 프레임에 대한 16자 해시입니다. 크래시 중복 제거에 사용됩니다.
- **영구 코퍼스** — `<workspace>/corpus/harness_<id>/`에 위치한 하네스별 디렉터리로, 동일한 캠페인의 반복 및 재실행에 걸쳐 AFL의 흥미로운 입력을 유지합니다.
- **스마트 뮤테이터** — 스플라이스 토큰이 대상 자체의 소스 코드에서 추출되는 `LLVMFuzzerCustomMutator`입니다 (`generate_smart_mutator`).
- **커스텀 뮤테이터 (libFuzzer)** — 버퍼를 어떻게 변이할지에 대한 완전한 자유를 가지고 엔진이 호출하는 사용자 제공 C 함수입니다; AFL++는 동일한 ABI를 지원합니다.
- **MCP 도구** — LLM 에이전트가 호출할 수 있는 FastMCP 데코레이트된 함수입니다.
- **OSS-Fuzz / Fuzz-Introspector** — Google의 오픈소스 퍼징 인프라와 그 동반 콜 그래프/커버리지 분석 도구입니다. 이 태스크플로우의 여러 기능(형식별 뮤테이터, 스택별 중복 제거, 콜 그래프 + 미접촉 API 리포트, 다중 후보 하네스)은 이들에서 영감을 받았습니다.

---

## 라이선스

이 프로젝트는 MIT 오픈 소스 라이선스 조건에 따라 라이선스가 부여됩니다. 전체 조건은 [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) 파일을 참조하세요.

## 메인테이너

[CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS)를 참조하거나 GitHub Security Lab 팀에 문의하세요.

## 지원

이 프로젝트에 대한 도움을 받는 방법에 대한 자세한 내용은 [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md)를 참조하세요.

## 감사의 글

이 프로젝트는 [AFL++](https://github.com/AFLplusplus/AFLplusplus), [OSS-Fuzz](https://github.com/google/oss-fuzz), 그리고 [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector)의 개념과 기법을 기반으로 구축되었습니다.