/<org-slug>/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 스크립트를 작성하고 실행 (네트워크 없음, 파일시스템 접근 없음, 비밀 정보 제거),
- 충분한 근거가 있는 각 개선 사항 기록.
- 권고사항 (구체적인 변경 내용 — 프롬프트 수정, 도구 스키마 수정, 재시도 정책, 가드레일, 추가 평가 커버리지),
- 예상 효과 및 작업량 추정치 (낮음 / 중간 / 높음),
- 중요도 —
big(운영자에게 즉시 알림 필요),medium(실행 보고서에 포함),small(대시보드 컨텍스트), - 안정적인 지문 (이번 실행의 세션이 아닌 이슈의 카테고리 + 범위 기반) — 근거가 바뀌더라도 동일한 이슈를 실행 간에 추적할 수 있도록,
- 재발을 감지할 수 있는 단순한 결정론적 감시가 가능한 경우, 클릭 한 번으로 생성할 수 있는 제안 알림.
AI 계층은 선택 사항이지만 권장됩니다. 감사 파이프라인에 AI 에이전트가 구성되어 있지 않더라도 실행은 계속되며, 정책 발견 사항은 영속 저장됩니다. 에이전트 계층에 대해서는 조용히 통과시키는 대신 “분석 불가”로 정직하게 보고합니다.
실패 모드
개선 사항은 조직의 영속적인 실패 모드 카탈로그로 분류되거나 새로운 모드를 제안합니다. 모드는 실행 간 및 장기적인 재발 추적에서 패턴에 안정적인 식별자를 부여합니다.분류 생명주기
발견 사항 페이지(/audits/<id>/findings/<finding-id>)에서:
| 작업 | 효과 |
|---|---|
| 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에 문서화되어 있습니다.
API
모든 엔드포인트는 조직 범위로 제한되며 표준 베어러 키 인증을 따릅니다(api-keys.md 참조).| 엔드포인트 | 권한 | 목적 |
|---|---|---|
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"}. |