> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # 감사(Audits) — 에이전트 개선 사항 탐지 > AgentEye Audits — 에이전트 개선 사항 탐지 문서입니다. 감사(Audit)는 **여러 세션에 걸쳐** 에이전트 로그를 분석하여 개선이 필요한 사항을 찾아내는 반복 실행 작업입니다. 알림(alert)이 이미 알고 있는 특정 지표를 거의 실시간으로 감시하는 것과 달리, 감사는 *조사*를 수행합니다. 설정한 일정에 따라 해당 기간 동안 결정론적 정책 검사를 실행한 뒤, **AI 안정성 에이전트**를 세션 전반에 걸쳐 자유롭게 투입합니다. 에이전트는 데이터를 직접 쿼리하고 의심스러운 트랜스크립트를 읽으며, 필요한 경우 소규모 분석 스크립트를 실행한 후 각 항목의 근거와 함께 **개선 권고사항**을 작성합니다. 감사는 "내 에이전트에서 무엇을 수정하거나 개선해야 하는가?"라는 질문에 답하는 데 활용하고, 알림은 특정 임계값이 초과되는 순간 즉시 통보받기 위해 사용하세요. 모든 개선 사항은 근거가 된 정확한 세션 및 쿼리와 연결되며, 클릭 한 번으로 재발을 감지하는 알림을 미리 채워진 상태로 생성할 수 있습니다. 대시보드 화면은 **`//audits`** (사이드바 → *분석* → *감사*)이며, `audits:read` / `audits:write` 권한으로 접근을 제한합니다. *** ## 실행 방식 각 실행은 결정론적 기반 계층과 에이전트 조사 계층, 두 가지 단계로 구성됩니다. ### 1. 정책 검사 (결정론적) 어떤 모델도 실행되기 전에, 감사는 해당 기간에 대해 소규모 **SQL 정책 검사** 카탈로그를 실행합니다. 이는 알려진 문제 패턴을 감지하고 일치하는 이벤트 *수* / 세션이 *무엇인지*를 보고하는 범위가 제한된 집계 쿼리이며, 일치한 텍스트 자체는 보고하지 않습니다. 카탈로그에는 다음이 포함됩니다: * 이벤트 페이로드의 **비밀/자격증명 유출** — AWS 액세스 키, `sk-…` API 키, PEM 개인 키, JWT / 베어러 토큰, `KEY=…` 형식의 자격증명 할당. * **프롬프트 인젝션 마커** — "이전 지시를 무시하라", "시스템 프롬프트를 공개하라" 등 유사한 표현. * **개인식별정보(PII)** — SSN 형식의 숫자 (휴리스틱 기반). * **도구 권한 거부** 및 **무한 도구 호출 루프**. 정책 적중 사항은 (`policy` 종류의) 발견 사항으로 영속 저장되며 **항상 표시됩니다** (실행당 상한선에 의해 잘리지 않습니다). 또한 AI 에이전트에게 초기 단서로 전달됩니다. 이 계층은 모델이 필요하지 않기 때문에, AI 에이전트를 사용할 수 없는 경우에도 감사는 가장 중요한 보안 신호를 계속 생성합니다. ### 2. 에이전트 조사 (AI) 이후 감사는 **자율 안정성 에이전트**(대시보드 어시스턴트를 구동하는 것과 동일한 Claude Agents SDK 서비스에 감사 전용 프롬프트 적용)를 실행합니다. 에이전트는 감사의 **범위** (선택된 에이전트 × 환경) 및 **기간**을 기반으로 다음을 수행합니다: * 분석 테이블에 대해 읽기 전용 SQL 쿼리 실행, * 대표적인 세션 트랜스크립트 일부 읽기, * SQL로 표현할 수 없는 분석(오류 클러스터링, 분포 계산, 이미 가져온 페이로드 스위핑)을 위해 필요시 **격리된 인팟(in-pod) 샌드박스**에서 짧은 **Python 스크립트를 작성하고 실행** (네트워크 없음, 파일시스템 접근 없음, 비밀 정보 제거), * 충분한 근거가 있는 각 **개선 사항** 기록. 에이전트는 감사의 **민감도** (낮음 / 중간 / 높음)에 따라 오류 클러스터링, 기준선 대비 드리프트, 트랜스크립트의 목표 달성 실패, 도구 오용, 품질/비용 절충, 커버리지 공백 등 여러 조사 항목을 검토합니다. 모든 개선 사항은 **근거를 인용해야** 합니다. 즉, 에이전트가 실제로 검사한 세션 ID 및/또는 실행한 SQL이 있어야 합니다. 서버는 인용된 세션이 존재하는지 검증하고, **유효한 근거가 없는 개선 사항은 폐기**합니다. 에이전트는 조사하지만 결코 날조하지 않습니다. 각 개선 사항에는 다음이 포함됩니다: * **권고사항** (구체적인 변경 내용 — 프롬프트 수정, 도구 스키마 수정, 재시도 정책, 가드레일, 추가 평가 커버리지), * **예상 효과** 및 **작업량** 추정치 (낮음 / 중간 / 높음), * **중요도** — `big` (운영자에게 즉시 알림 필요), `medium` (실행 보고서에 포함), `small` (대시보드 컨텍스트), * 안정적인 **지문** (이번 실행의 세션이 아닌 이슈의 카테고리 + 범위 기반) — 근거가 바뀌더라도 동일한 이슈를 실행 간에 추적할 수 있도록, * 재발을 감지할 수 있는 단순한 결정론적 감시가 가능한 경우, 클릭 한 번으로 생성할 수 있는 **제안 알림**. > **AI 계층은 선택 사항이지만 권장됩니다.** 감사 파이프라인에 AI 에이전트가 구성되어 있지 않더라도 실행은 계속되며, 정책 발견 사항은 영속 저장됩니다. 에이전트 계층에 대해서는 조용히 통과시키는 대신 "분석 불가"로 정직하게 보고합니다. ### 실패 모드 개선 사항은 조직의 영속적인 **실패 모드 카탈로그**로 분류되거나 새로운 모드를 제안합니다. 모드는 실행 간 및 장기적인 재발 추적에서 패턴에 안정적인 식별자를 부여합니다. ## 분류 생명주기 발견 사항 페이지(`/audits//findings/`)에서: | 작업 | 효과 | | ------------------------------- | ----------------------------------------------------------------------------------------------- | | **acknowledge(확인)** | 발견 사항을 표시 상태로 유지하되 우선순위를 절반으로 낮춥니다. | | **resolve(해결)** | 수정된 것으로 표시합니다. 이후 해당 패턴이 실제로 재발하면 **신규**로 재개됩니다 — 회귀가 조용히 기록에 묻히지 않고 명확히 드러납니다. | | **mute(음소거)** / **dismiss(무시)** | 영속적 억제: 패턴의 지문이 기억되어 실행이 바뀌어도 다시 표시되지 않습니다. mute는 "알려진, 수용된 문제"에, dismiss는 "유용하지 않은 항목"에 사용하세요. | | **reopen(재열기)** | 억제/해결을 해제하고 패턴의 순위를 다시 적용합니다. | 저신호 노이즈는 에이전트 개선 사항에 대한 실행당 발견 상한선(`top_k`)으로 감사별로 제어됩니다. 정책 발견 사항은 보안과 관련이 있어 항상 표시되므로 상한선을 적용받지 않습니다. 상한선으로 제외된 항목은 실행 통계에 집계되며, 아무것도 조용히 삭제되지 않습니다. ## 스케줄링 * **주기** (`schedule_interval_secs`): 시간별부터 주별; **기본값은 일별**입니다. 감사는 의도적으로 알림보다 주기가 깁니다 — 에이전트 조사는 전체 기간을 스캔하며 수 분이 소요됩니다. * **기간**: 고정 롤링 룩백(예: "각 실행은 지난 7일을 스캔") 또는 **마지막 실행 이후**(기본값) — 각 실행은 이전의 성공적인 실행이 끝난 지점부터 소폭 겹치는 구간을 포함하여 시작하므로 경계 이벤트를 놓치지 않습니다. * 다음 실행은 이전 실행이 **완료된** 후 전체 주기만큼 지난 시점에 예약되므로, 느린 실행이 동일한 감사의 두 번째 동시 실행을 생성하지 않습니다. * 감사 페이지의 **지금 실행**을 클릭하면 즉시 실행 대기 상태가 됩니다. ## 모델 선택 감사를 생성할 때 조사에 사용할 모델을 **운영자가 에이전트 서비스에 구성한 모델 목록**에서 선택할 수 있습니다. 모델이 하나만 구성된 경우 선택기는 해당 모델을 캡션으로 표시하고, 여러 개인 경우 직접 선택합니다. 설정하지 않으면 구성된 기본값을 사용합니다. ## 알림 실행에서 **신규** 발견 사항이 나타나면 감사는 조직에 구성된 채널로 알림을 전송합니다. 알림 파이프라인과 동일한 `alerts.enabled_channels` 게이트 및 설정을 사용합니다: * **Slack** — 중요한(`big`) 신규 항목 요약과 딥 링크. * **이메일** — 신규 개선 사항(최고 심각도, 항목별 권고사항, 딥 링크)을 정리한 **감사 보고서**. 감사에 **이메일** 채널이 연결되어 있고 신규 발견 사항이 하나 이상 있을 때 전송됩니다. 이미 알려진 반복 발견 사항은 재알림을 보내지 않습니다. ## 구성 참조 감사 정의는 대시보드(`/audits/new`) 또는 API를 통해 관리합니다. 감사별 설정에는 스케줄 주기 및 기간, 범위(`{"environments": [...], "agent_ids": [...]}`), 민감도(`low` / `medium` / `high`), 알림 채널, 실행당 발견 상한선(`top_k`), 모델(`llm_budget.model` 경유)이 포함됩니다. 운영자 수준 서버 설정(타임아웃, 샌드박스, 에이전트 서비스 URL)은 [deployment.md](/ko/agenteye/deployment)에 문서화되어 있습니다. ## API 모든 엔드포인트는 조직 범위로 제한되며 표준 베어러 키 인증을 따릅니다([api-keys.md](/ko/agenteye/api-keys) 참조). | 엔드포인트 | 권한 | 목적 | | ------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------ | | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 감사 정의 목록 조회 / 생성. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | 감사 조회, 수정, 삭제. | | `POST /audits/:id/run` | `audits:write` | 감사를 즉시 실행 대기 상태로 만듭니다. | | `GET /audits/:id/runs` | `audits:read` | 실행 기록 (기간, 상태, 통계, 발견 사항 수). | | `GET /audits/findings` | `audits:read` | 조직 전체 발견 사항 — `audit_id`, `status`로 필터링 가능, 우선순위 순 정렬. | | `GET /audits/findings/:fid` | `audits:read` | 발견 사항 전체 상세 정보 (권고사항, 근거, 우선순위). | | `POST /audits/findings/:fid/status` | `audits:write` | 분류: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | "감사가 실행되었으나 아무것도 발견하지 못한 경우", "코드 샌드박스가 비활성화된 경우", "감사 이메일이 전달되지 않은 경우"에 대해서는 [troubleshooting.md](/ko/agenteye/troubleshooting#audits)를 참조하세요.