<p align="center">
  <h1 align="center">Agent-Aegis</h1>
  <p align="center">
    <strong>코드베이스에서 보호되지 않은 AI 호출을 찾으세요. 프로덕션 전에 수정하세요.</strong>
  </p>
  <p align="center">
    <code>pip install agent-aegis && aegis scan .</code> — 30초 만에 15개 프레임워크에서 보호되지 않은 AI 호출을 탐지합니다.<br/>
    한 줄로 전부 보호: <code>aegis.auto_instrument()</code> — 12개 프레임워크에 인젝션 차단, PII 마스킹, 감사 추적을 코드 변경 없이 추가합니다.
  </p>
</p>

<p align="center">
  <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://github.com/Acacian/aegis/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/agent-aegis/"><img src="https://img.shields.io/pypi/v/agent-aegis?color=blue&cacheSeconds=3600" alt="PyPI"></a>
  <a href="https://pypi.org/project/langchain-aegis/"><img src="https://img.shields.io/pypi/v/langchain-aegis?label=langchain-aegis&color=blue&cacheSeconds=3600" alt="langchain-aegis"></a>
  <a href="https://pypi.org/project/agent-aegis/"><img src="https://img.shields.io/pypi/pyversions/agent-aegis?cacheSeconds=3600" alt="Python"></a>
  <a href="https://github.com/Acacian/aegis/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
  <a href="https://acacian.github.io/aegis/"><img src="https://img.shields.io/badge/docs-acacian.github.io%2Faegis-blue" alt="Docs"></a>
  <br/>
  <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-6100%2B_passed-brightgreen" alt="Tests"></a>
  <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="Coverage"></a>
  <a href="https://acacian.github.io/aegis/playground/"><img src="https://img.shields.io/badge/playground-브라우저에서_체험-ff6b6b" alt="Playground"></a>
  <a href="https://acacian.github.io/aegis/playground/scan-report.html"><img src="https://img.shields.io/badge/스캔_리포트-39개_레포%2C_92%25_F-red" alt="Scan Report"></a>
  <a href="https://www.bestpractices.dev/projects/12253"><img src="https://www.bestpractices.dev/projects/12253/badge" alt="OpenSSF Best Practices"></a>
</p>

<p align="center">
  <a href="#30초-체험"><strong>30초 체험</strong></a> &bull;
  <a href="#ci에-추가"><strong>CI에 추가</strong></a> &bull;
  <a href="#자동-계측">자동 계측</a> &bull;
  <a href="#정책-cicd">정책 CI/CD</a> &bull;
  <a href="#빠른-시작">빠른 시작</a> &bull;
  <a href="https://acacian.github.io/aegis/">문서</a> &bull;
  <a href="https://acacian.github.io/aegis/playground/"><strong>Playground</strong></a>
</p>

<p align="center">
  <a href="./README.md">English</a> &bull;
  <b>한국어</b>
</p>

---

## 30초 체험

```bash
pip install agent-aegis
aegis scan .
```

```
Aegis Governance Scan
=====================
Scanned: 47 files in ./src

Found 5 ungoverned tool call(s):
  agent.py:12   OpenAI        function call with tools= — no governance wrapper  [ASI02: Tool Misuse]
    → Wrap with aegis: import aegis; aegis.auto_instrument()
  tools.py:8    LangChain     @tool "search_db" — no policy check  [ASI02: Tool Misuse]
    → Wrap with aegis: import aegis; aegis.auto_instrument()
  llm.py:21     LiteLLM       litellm.completion() — no governance wrapper  [ASI02: Tool Misuse]
    → Wrap with aegis: import aegis; aegis.auto_instrument()
  run.py:5      subprocess    subprocess.run — direct shell execution  [ASI08: Uncontrolled Code Execution]
    → Use aegis sandbox policy to govern shell execution
  api.py:14     HTTP          requests.post — raw HTTP in agent code  [ASI07: Data Leakage]
    → Route through aegis-governed HTTP client or add policy rule

OWASP Agentic Top 10 Risks:
  ASI02: Tool Misuse & Exploitation: 3 finding(s)
  ASI07: Data Leakage & Exfiltration: 1 finding(s)
  ASI08: Uncontrolled Code Execution: 1 finding(s)

Governance Score: D (5 ungoverned call(s))
```

`--format json|sarif|suggest`, `--threshold A-F`, `--no-fixes`, `.aegisscanignore`, `# aegis: ignore` 인라인 프라그마를 지원합니다.

## CI에 추가

```yaml
- uses: Acacian/aegis@v0.9.2
  with:
    command: scan
    fail-on-ungoverned: true
```

모든 PR이 스캔됩니다. 보호되지 않은 AI 호출이 있으면 머지가 차단됩니다. [전체 옵션 보기](action.yml).

---

## 자동 계측

한 줄로 모든 프로젝트에 가드레일을 추가합니다. 리팩토링 불필요.

```python
import aegis
aegis.auto_instrument()

# LangChain, CrewAI, OpenAI, Anthropic, LiteLLM, Google GenAI,
# Pydantic AI, LlamaIndex, Instructor, DSPy 호출이 자동으로:
#   - 프롬프트 인젝션 탐지 (공격 차단)
#   - PII 탐지 (개인정보 노출 경고)
#   - 프롬프트 유출 탐지 (시스템 프롬프트 추출 경고)
#   - 전체 감사 추적 (모든 호출 기록)
```

환경변수로도 가능 — 코드 변경 제로:

```bash
AEGIS_INSTRUMENT=1 python my_agent.py
```

### 지원 프레임워크

| 프레임워크 | 패치 대상 | 상태 |
|-----------|----------|------|
| **LangChain** | `BaseChatModel.invoke/ainvoke`, `BaseTool.invoke/ainvoke` | Stable |
| **CrewAI** | `Crew.kickoff/kickoff_async`, global `BeforeToolCallHook` | Stable |
| **OpenAI Agents SDK** | `Runner.run`, `Runner.run_sync` | Stable |
| **OpenAI API** | `Completions.create` (chat & completions) | Stable |
| **Anthropic API** | `Messages.create` | Stable |
| **LiteLLM** | `completion`, `acompletion` | Stable |
| **Google GenAI** | `Models.generate_content` (신/구) | Stable |
| **Pydantic AI** | `Agent.run`, `Agent.run_sync` | Stable |
| **LlamaIndex** | `LLM.chat/achat/complete/acomplete`, `BaseQueryEngine.query/aquery` | Stable |
| **Instructor** | `Instructor.create`, `AsyncInstructor.create` | Stable |
| **DSPy** | `Module.__call__`, `LM.forward/aforward` | Stable |

### 기본 가드레일

| 가드레일 | 기본 동작 | 탐지 대상 |
|---------|---------|----------|
| **프롬프트 인젝션** | 차단 | 10개 공격 카테고리, 85+ 패턴, 다국어 (EN/KO/ZH/JA) |
| **PII 탐지** | 경고 | 13개 카테고리 (이메일, 신용카드, SSN, IBAN, API 키 등) |
| **프롬프트 유출** | 경고 | 시스템 프롬프트 추출 시도 |
| **유해 콘텐츠** | 경고 | 유해, 폭력적, 학대적 콘텐츠 |

모든 가드레일은 결정론적 regex — LLM 호출 없음, 네트워크 없음. **콜드 2.65ms / 캐시 <1us**. [벤치마크](benchmarks/).

---

## 정책 CI/CD

보안 도구는 런타임을 보호합니다. Aegis는 정책 생명주기도 관리합니다.

### `aegis plan` — 배포 전 미리보기

```bash
aegis plan current.yaml proposed.yaml --audit-db aegis_audit.db

# Policy Impact Analysis
#   Rules: 2 added, 1 removed, 3 modified
#   Impact (replayed 1,247 actions):
#     23 actions would change from AUTO → BLOCK
```

### `aegis test` — 정책 회귀 테스트

```bash
aegis test policy.yaml tests.yaml              # CI에서 실행
aegis test policy.yaml --generate              # 테스트 자동 생성
aegis test new.yaml tests.yaml --regression old.yaml  # 회귀 검사
```

```yaml
# .github/workflows/policy-check.yml
- uses: Acacian/aegis@main
  with:
    policy: aegis.yaml
    tests: tests.yaml
    fail-on-regression: true
```

---

## 빠른 시작

### 1. 설치

```bash
pip install agent-aegis
```

### 2. 자동 계측 (권장)

```python
import aegis
aegis.auto_instrument()
# 12개 프레임워크가 즉시 보호됩니다.
```

### 3. YAML 정책으로 세밀한 제어

```bash
aegis init  # aegis.yaml 생성
```

```yaml
# aegis.yaml
guardrails:
  pii: { enabled: true, action: mask }
  injection: { enabled: true, action: block, sensitivity: medium }

policy:
  version: "1"
  defaults:
    risk_level: medium
    approval: approve
  rules:
    - name: read_safe
      match: { type: "read*" }
      risk_level: low
      approval: auto
    - name: no_deletes
      match: { type: "delete*" }
      risk_level: critical
      approval: block
```

### 4. 결과 확인

```bash
aegis audit
```
```
  ID  Session       Action        Target   Risk      Decision    Result
  1   a1b2c3d4...   read          crm      LOW       auto        success
  2   a1b2c3d4...   bulk_update   crm      HIGH      approved    success
  3   a1b2c3d4...   delete        crm      CRITICAL  block       blocked
```

---

## 설치 옵션

```bash
pip install agent-aegis                   # 코어 (12개 프레임워크 자동 계측 포함)
pip install langchain-aegis               # LangChain 독립 통합
pip install 'agent-aegis[mcp]'            # MCP 서버 + 프록시
pip install 'agent-aegis[server]'         # REST API + 대시보드
pip install 'agent-aegis[all]'            # 전부
```

### MCP 프록시 — 코드 변경 없이 MCP 서버 보호

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["--from", "agent-aegis[mcp]", "aegis-mcp-proxy",
               "--wrap", "npx", "-y",
               "@modelcontextprotocol/server-filesystem", "/home"]
    }
  }
}
```

Claude Desktop, Cursor, VS Code, Windsurf에서 사용 가능. 툴 포이즈닝 탐지, 러그풀 탐지, 인자 살균, 정책 평가, 전체 감사 추적.

---

## 왜 Aegis인가?

| | 직접 구현 | 플랫폼 가드레일 | 엔터프라이즈 플랫폼 | **Aegis** |
|---|---|---|---|---|
| **설정** | if/else 며칠 | 벤더별 설정 | K8s + 구매 프로세스 | **`pip install` + 한 줄** |
| **코드 변경** | 모든 호출 래핑 | SDK별 통합 | 수개월 통합 | **제로 — 런타임 자동 계측** |
| **크로스 프레임워크** | 프레임워크별 재작성 | 자사 생태계만 | 보통 단일 벤더 | **12개 프레임워크** |
| **정책 CI/CD** | 없음 | 없음 | 없음 | **`aegis plan` + `aegis test`** |
| **감사 추적** | printf 디버깅 | 플랫폼 로그만 | 클라우드 대시보드 | **SQLite + JSONL + 웹훅** |
| **컴플라이언스** | 수동 문서화 | 없음 | 엔터프라이즈 영업 | **EU AI Act, NIST, SOC2 내장** |
| **비용** | 엔지니어링 시간 | 무료~$$$ | $$$$ + 인프라 | **무료 (MIT). 영원히.** |

### Aegis만의 차별점

다른 도구는 입출력을 검사합니다. Aegis는 결정 자체를 거버닝합니다.

| 기능 | 의미 | 근거 |
|---|---|---|
| **Selection Governance** | 에이전트가 *제외한 것*을 감사합니다. 위험한 옵션을 "도움이 되려고" 빼는 모델은 선택 권력을 행사하는 것 — Aegis가 이를 탐지합니다. | [Santander et al., arXiv:2602.14606](https://arxiv.org/abs/2602.14606) |
| **Justification Gap** | 6차원 비대칭 스코어링: 에이전트가 영향을 선언하면 Aegis가 독립 평가합니다. 과소 보고 시 에스컬레이션 또는 차단. | COA-MAS (Carvalho) |
| **3분할 ActionClaim** | 모든 툴 콜이 Declared(에이전트 작성, 비신뢰), Assessed(Aegis 계산), Chain(위임) 필드로 분리. 구조적 분리로 표면적 정렬(cosmetic alignment)을 탐지 가능. | — |
| **단조 신뢰 제약** | 위임된 에이전트는 자기 권한을 상승시킬 수 없습니다. 체인을 따라 신뢰 수준은 비증가 — 위반 시 자동 차단. | 격자 기반 접근 제어 |
| **풀 라이프사이클** | Scan(탐지) → Instrument(보호) → Policy CI/CD(테스트) → Runtime(거버닝) → Proxy(게이트웨이) → Audit(추적). 라이브러리 하나, `pip install` 한 번. | — |

---

## CLI

```bash
aegis scan ./src/                       # 보호되지 않은 AI 호출 탐지
aegis score ./src/ --policy policy.yaml # 거버넌스 점수 (0-100)
aegis init                              # 시작 정책 생성
aegis validate policy.yaml              # 문법 검증
aegis plan current.yaml proposed.yaml   # 정책 변경 미리보기
aegis test policy.yaml tests.yaml       # 정책 회귀 테스트
aegis audit                             # 감사 로그 조회
aegis serve policy.yaml                 # REST API + 대시보드
aegis probe policy.yaml                 # 적대적 정책 테스트
aegis autopolicy "삭제 차단"             # 자연어 → YAML
```

## 문서

전체 문서: **[acacian.github.io/aegis](https://acacian.github.io/aegis/)**

- [통합 가이드](https://acacian.github.io/aegis/) — LangChain, CrewAI, OpenAI, MCP 등
- [정책 레퍼런스](https://acacian.github.io/aegis/) — 조건, 템플릿, 베스트 프랙티스
- [보안 기능](https://acacian.github.io/aegis/) — 가드레일, 이상 탐지, 컴플라이언스
- [아키텍처](ARCHITECTURE.md) — 코드베이스 구조
- [인터랙티브 Playground](https://acacian.github.io/aegis/playground/) — 브라우저에서 체험

## 기여

```bash
git clone https://github.com/Acacian/aegis.git && cd aegis
make dev      # 의존성 + 훅 설치
make test     # 테스트 실행
make lint     # 린트 + 포맷 검사
```

[기여 가이드](CONTRIBUTING.md) &bull; [Good First Issues](https://github.com/Acacian/aegis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) &bull; [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Acacian/aegis)

## 라이선스

MIT -- [LICENSE](LICENSE) 참조.

Copyright (c) 2026 구동하 (Dongha Koo, [@Acacian](https://github.com/Acacian)). Created March 21, 2026.

---

<p align="center">
  <sub>AI 에이전트를 위한 Policy CI/CD. 자율 AI 에이전트 시대를 위해 만들어졌습니다.</sub><br/>
  <sub>Aegis가 도움이 되셨다면, 스타를 눌러주세요 — 다른 사람들이 찾는 데 도움이 됩니다.</sub>
</p>
