Metadata-Version: 2.4
Name: raon
Version: 0.0.0
Summary: LLM 기반 취약점 발견 시스템 — 퍼징 · 멀티에이전트 오케스트레이션 · 바이너리 분석을 하나의 피드백 루프로 (이름 선점용 pre-alpha 플레이스홀더)
Project-URL: Homepage, https://github.com/cpprhtn/raon
Project-URL: Repository, https://github.com/cpprhtn/raon
Author: Junwon Lee
License: MIT License
        
        Copyright (c) 2026 Junwon Lee
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: binary-analysis,fuzzing,llm,multi-agent,security,vulnerability
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# raon

> **LLM 기반 취약점 발견 시스템** — LLM에게 "버그를 찾게" 하지 않고,
> "버그를 찾아낼 최고의 테스트베드를 자동 생성·운영"하게 한다.

`raon`은 퍼징 · 멀티에이전트 오케스트레이션 · 바이너리 분석을 **하나의 닫힌 피드백 루프**로
묶어, 알려진/미지의 소프트웨어 취약점을 자동으로 발견·트리아지하는 연구용 프레임워크입니다.

> ⚠️ **상태: 초기 개발 단계 (pre-alpha).** 현재 이 패키지는 이름 선점용 플레이스홀더이며,
> 공개 API는 아직 제공되지 않습니다. 설계 및 로드맵은 아래를 참고하세요.

---

## 설계 원칙

핵심 원칙 세 가지 — 이걸 어기면 프로젝트가 무너집니다.

1. **LLM은 전략층에만 둔다 (hot loop 금지).** 퍼저는 초당 수천~수백만 exec, LLM은 초당 ~1 call.
   둘을 같은 루프에 넣으면 퍼저가 LLM 속도로 느려진다. LLM은 *어디를·무엇으로·어떻게* 칠지
   정하는 층에만 개입한다.
2. **기존 인프라를 재구현하지 않는다.** ASan/TSan, AFL++, SanitizerCoverage, angr, Ghidra는
   이미 검증됨. 우리는 이걸 *조립·해석·연결*한다. 새로움은 "래핑"이 아니라 "오케스트레이션/추론"에 있다.
3. **수직 슬라이스 먼저, 3개 타워 나중에.** 얇은 실 하나(한 타겟 → 한 하네스 → 한 크래시 → 한 트리아지)를
   3개 컴포넌트에 관통시켜 *유기적 결합을 먼저 증명*한다.

---

## 아키텍처 — 3개 컴포넌트 = 하나의 루프

세 컴포넌트는 파이프라인이 아니라 **닫힌 피드백 루프**로 결합합니다.
모든 컴포넌트는 공유 저장소(KnowledgeBase · TargetStore · Corpus · FindingStore)의
**공유 계약(Shared Contracts)** 위에서만 대화하므로 느슨하게 결합됩니다.

| 컴포넌트 | 역할 | 대표 기반 도구 |
|---|---|---|
| **퍼징 엔진** | 목표지향(directed greybox) 커버리지 유도 퍼징으로 크래시 확보. LLM은 ① 하네스 자동합성 ② 시드/문법 생성 ③ stuck-branch escape 세 지점에만 개입 | AFL++ / libFuzzer / LibAFL, SanitizerCoverage, ASan/UBSan |
| **멀티에이전트 오케스트레이션** | 루프 상단(계획: 우선순위·하네스 요청·시드 선택)과 하단(트리아지: dedup·충돌해소·exploitability 랭킹)에 위치. **진짜 기여는 에이전트가 아니라 오케스트레이션** | Supervisor + Agent A/B/C (블랙보드 패턴), CodeQL/Semgrep |
| **바이너리 분석 연동** | 소스 없는 타겟 구조화(앞단)와 크래시 주소 → 함수/타입 문맥 grounding(뒷단). 루프 양쪽 끝에 두 번 등장 | angr, Ghidra (headless), LIEF |

```
            ┌──────────────────────────────────────────────────────┐
            │      공유 저장소                                       │
            │  KnowledgeBase · TargetStore · Corpus · FindingStore  │
            └──────────────────────────────────────────────────────┘
                 ▲            ▲              ▲              ▲
   ┌─────────────┴───┐  ┌─────┴──────┐  ┌────┴─────────┐  ┌┴─────────────────┐
   │ 바이너리 분석    │→ │ 멀티에이전트 │→ │ 퍼징 엔진     │→ │ 멀티에이전트      │
   │ (타겟 구조화)    │  │ (계획)      │  │ (커버리지 유도)│  │ (트리아지)        │
   └──────────────────┘  └─────────────┘  └──────────────┘  └───────────────────┘
                                                                    │
                     피드백: 우선순위 갱신 · 새 하네스 요청 · 시드 정제 (루프 상단으로)
```

---

## 공유 계약 (Shared Contracts)

3개 컴포넌트가 유기적으로 붙는 이유는 전부 여기서 나옵니다. 각 컴포넌트는 이 스키마만 알면 됩니다.

- **`TargetDescriptor`** — "무엇을 테스트하는가" (시그니처·진입 경로·도메인 태그·우선순위)
- **`Corpus` / 커버리지 상태** — "탐색이 어디까지 갔나" (시드·edge coverage·stuck_branches)
- **`Finding`** — "버그 후보 하나" (정규화된 보고 단위, 이종 증거를 한 테이블에서 비교)
- **`KnowledgeBase`** — 도메인 사전 (문법·시드 템플릿·불변식·취약 인터페이스)

---

## 데이터 흐름 (한 사이클)

```
1. Ingest    : 소스/바이너리 → TargetDescriptor[]
2. Plan      : priority_score 부여, 하네스 합성, 시드/문법 선택
3. Explore   : 타겟별 커버리지 유도 퍼징 → Corpus 갱신 + Finding(동적)
4. Ground    : 크래시 주소 → 함수/타입 문맥 복원 (소스 없을 때)
5. Reason    : 정적/추론 Finding 생성
6. Triage    : dedup → 충돌해소 → exploitability 랭킹
7. Feedback  : 우선순위 갱신 · 새 하네스 요청 · stuck 시드 정제 → (2)로
```

---

## 로드맵

| Phase | 목표 |
|---|---|
| **P0** | 공유 계약 확정 + 벤치마크 세팅 (스키마 4종, Magma/Juliet 로컬 구동) |
| **P1** | 수직 슬라이스 v0 — 하네스 자동합성 1건 → 크래시 → 트리아지 1건 |
| **P2** | 퍼징 심화 — directed greybox + stuck-escape LLM, 시드 진화 |
| **P3** | 오케스트레이션 심화 — 멀티에이전트 vs 단일 베이스라인 정량 비교 |
| **P4 (스트레치)** | 바이너리 분석 — 소스 없는 타겟으로 확장 (디컴파일 → 타입복원 → 하네스) |

---

## 평가 전략

- **Magma** — 실제 CVE 재주입 벤치마크 (ground truth 有)
- **Juliet / SARD** — 카테고리별 합성 취약점으로 정적 추론 정밀도·재현율 측정
- **OSS-Fuzz 과거 버그** — 재현성 스트레스 테스트
- 핵심 지표: `time-to-first-crash`, `unique bugs found`, `triage 정밀도(FP율)`,
  `dedup 정확도`, `단일 vs 멀티 에이전트 델타`

---

## 설치

```bash
pip install raon
```

> 현재 배포되는 것은 이름 선점용 플레이스홀더입니다. 실사용 가능한 릴리스는 추후 공지됩니다.

---

## 라이선스

[MIT](LICENSE) © 2026 Junwon Lee
