# 에이전트가 한 일을 추적하는 감사 로그: 호출마다 실행 주체와 도구를 남기기

> 에이전트들이 서비스 계정 하나로 도구를 부르면 누가 무엇을 했는지 로그에 남지 않습니다. 호출마다 agent_id, session_id, run_id 를 붙여 OpenSearch 에 색인하고, Dashboards 에서 호출 순서를 재구성하고 승인 없는 삭제를 잡아냅니다.

- 주소: https://copyandrun.com/blog/llm-agent-audit-log-opensearch/
- 분야: AI 보안
- 발행일: 2026-10-25
- 태그: LLM, 에이전트, 감사 로그, OpenSearch

LLM 에이전트가 파일을 읽고, 메일을 보내고, 파일을 지우는 도구를 부를 때 그 호출이 로그에 어떻게 남는지 확인합니다. 에이전트 여러 개가 같은 서비스 계정으로 도구 서버에 붙으면, 서버 로그에는 계정 이름과 도구 이름만 남습니다. 어떤 에이전트의 어떤 실행에서 나온 호출인지는 알 수 없습니다.

이 글에서는 이 공백을 먼저 재현합니다. 그다음 도구 호출 프록시(Python, Flask)를 만들어 호출마다 `agent_id`, `session_id`, `run_id`, 도구 이름, 위험도, 마스킹한 인자 요약, 결과 상태, 지연 시간을 JSON 으로 남기고 OpenSearch 에 색인합니다. 마지막으로 OpenSearch Dashboards 에서 위험 도구 호출을 찾고, `run_id` 하나의 호출 순서를 재구성하고, 승인 없이 호출된 삭제에 경고 문서를 만듭니다. 모델 호출은 없고 도구 호출만 기록하므로 LLM 키나 Ollama 는 필요 없습니다.

이 글의 OpenSearch 와 Dashboards 는 보안 플러그인(TLS, 인증)을 끈 실습용 구성이므로 운영 클러스터에는 쓰지 않습니다. 포트는 모두 로컬 호스트(`127.0.0.1`)에만 연결합니다. 도구는 직접 만든 가짜 도구이며 컨테이너 안의 실습 폴더만 건드립니다.

## 준비물

| 항목 | 내용 |
|------|------|
| Docker | Docker Desktop 또는 Docker Engine, Compose v2 |
| OpenSearch, Dashboards | 3.2.0 (이미지 `opensearchproject/opensearch:3.2.0`, `opensearchproject/opensearch-dashboards:3.2.0`) |
| 프록시 | `python:3.12-slim` 컨테이너에 Flask 3.1.3 설치 |
| 호스트 Python | 3.12 (이 글의 스크립트는 표준 라이브러리만 사용, 3.12.10에서 확인) |
| 메모리 | OpenSearch 컨테이너는 1GB로 제한하고 힙은 512MB로 설정 |
| 호스트 포트 | 5740(OpenSearch), 5741(Dashboards), 5742(프록시) |

OpenSearch 설치와 ml-commons 설정은 이 글에서 다루지 않습니다. 같은 구성을 설명한 [Docker로 OpenSearch와 Ollama 띄워 비용 없는 AI-SIEM 만들기](/blog/opensearch-ollama-ai-siem/)를 참고합니다. 리눅스 호스트에서는 먼저 `sudo sysctl -w vm.max_map_count=262144` 를 실행합니다.

## 실습 파일 저장

작업 폴더 하나에 아래 파일 일곱 개를 같은 이름으로 저장합니다. 먼저 `docker-compose.yml` 입니다. 컨테이너 이름은 `cr-t11-` 로 시작하고, OpenSearch 는 메모리 1GB와 힙 512MB로 제한했습니다. 프록시는 `AUDIT` 값으로 감사 기록을 켜고 끕니다.

```yaml
name: cr-t11
services:
  opensearch:
    image: opensearchproject/opensearch:3.2.0
    container_name: cr-t11-opensearch
    mem_limit: 1g
    environment:
      - discovery.type=single-node
      - OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m
      - DISABLE_INSTALL_DEMO_CONFIG=true
      - DISABLE_SECURITY_PLUGIN=true # 실습 전용: 인증과 TLS를 끕니다
      - http.compression=false # 브라우저로 직접 열어 볼 때 응답이 비는 것을 막습니다
    ulimits:
      nofile: { soft: 65536, hard: 65536 }
    ports: ["127.0.0.1:5740:9200"]
    volumes: [opensearch-data:/usr/share/opensearch/data]
  dashboards:
    image: opensearchproject/opensearch-dashboards:3.2.0
    container_name: cr-t11-dashboards
    mem_limit: 1g
    environment:
      - OPENSEARCH_HOSTS=["http://opensearch:9200"]
      - DISABLE_SECURITY_DASHBOARDS_PLUGIN=true # 실습 전용: 로그인 화면을 끕니다
    ports: ["127.0.0.1:5741:5601"]
    depends_on: [opensearch]
  proxy:
    image: python:3.12-slim
    container_name: cr-t11-proxy
    command: sh -c "pip install -q flask==3.1.3 && python /app/app.py"
    environment:
      - AUDIT=${AUDIT:-1} # 0 이면 감사 기록 없이 도구만 실행합니다
      - OS_URL=http://opensearch:9200
    volumes: ["./app.py:/app/app.py:ro"]
    ports: ["127.0.0.1:5742:8000"]
    depends_on: [opensearch]
volumes:
  opensearch-data:
```

`app.py` 가 프록시입니다. 가짜 도구 세 개(`read_file`, `send_mail`, `delete_file`)는 컨테이너 안의 `/data` 폴더에서만 동작하고, 메일은 보낸 것처럼 응답만 합니다. 도구를 실행한 뒤 기존 방식의 한 줄 기록(`[tool-server]`)을 남기고, `AUDIT=1` 이면 감사 문서를 색인합니다.

```python
"""에이전트 도구 호출 프록시: 도구를 실행하고, 호출마다 감사 기록을 OpenSearch 에 색인합니다."""
import json
import os
import re
import threading
import time
import urllib.request
from datetime import datetime, timezone

from flask import Flask, jsonify, request

OS_URL = os.environ.get("OS_URL", "http://opensearch:9200")
AUDIT = os.environ.get("AUDIT", "1") == "1"
INDEX = "agent-audit"
SANDBOX = "/data"
SERVICE_ACCOUNT = "svc-agent"  # 모든 에이전트가 함께 쓰는 서비스 계정

app = Flask(__name__)
seq_lock = threading.Lock()
seq_by_run = {}


def seed_sandbox():
    os.makedirs(SANDBOX, exist_ok=True)
    files = {
        "report.txt": "2026년 3분기 보안 점검 보고서 초안입니다.\n",
        "notes.txt": "회의 메모: 계정 정리 일정은 다음 주에 정합니다.\n",
        "old-backup.txt": "오래된 백업 목록입니다.\n",
    }
    for name, text in files.items():
        with open(os.path.join(SANDBOX, name), "w", encoding="utf-8") as f:
            f.write(text)


def safe_path(name):
    path = os.path.realpath(os.path.join(SANDBOX, name))
    if not path.startswith(SANDBOX + os.sep):
        raise ValueError("허용 폴더 밖의 경로입니다")
    return path


def read_file(args):
    with open(safe_path(args["path"]), encoding="utf-8") as f:
        text = f.read()
    return {"chars": len(text)}


def send_mail(args):
    return {"queued": True}  # 실제로 보내지 않고 보낸 것처럼만 답합니다


def delete_file(args):
    os.remove(safe_path(args["path"]))
    return {"deleted": args["path"]}


TOOLS = {
    "read_file": (read_file, "low"),
    "send_mail": (send_mail, "medium"),
    "delete_file": (delete_file, "high"),
}

SENSITIVE_KEY = re.compile(r"pass|token|secret|key|authorization", re.I)
SECRET_VALUE = re.compile(r"(?i)(token|password|passwd|secret|api[_-]?key)\s*[=:]\s*\S+")


def mask(value):
    text = str(value)
    text = SECRET_VALUE.sub(r"\1=***", text)
    return text if len(text) <= 60 else text[:60] + "..."


def summarize(args):
    parts = []
    for key in sorted(args):
        shown = "***" if SENSITIVE_KEY.search(key) else mask(args[key])
        parts.append(f"{key}={shown}")
    return ", ".join(parts)


def index_audit(doc):
    req = urllib.request.Request(
        f"{OS_URL}/{INDEX}/_doc?refresh=true",
        data=json.dumps(doc, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        urllib.request.urlopen(req, timeout=3).read()
    except Exception as exc:  # 색인에 실패해도 도구 호출은 막지 않고 오류만 남깁니다
        print(f"[audit] index failed: {exc}", flush=True)


@app.post("/tools/<tool>")
def call_tool(tool):
    started = time.perf_counter()
    agent_id = request.headers.get("X-Agent-Id", "unknown")
    session_id = request.headers.get("X-Session-Id", "unknown")
    run_id = request.headers.get("X-Run-Id", "unknown")
    approval = request.headers.get("X-Approval-Id", "none")
    args = (request.get_json(silent=True) or {}).get("args", {})

    status, code = "ok", 200
    if tool not in TOOLS:
        result, status, code = {"error": "unknown tool"}, "error", 404
    else:
        try:
            result = TOOLS[tool][0](args)
        except Exception as exc:
            result, status, code = {"error": str(exc)}, "error", 400
    duration_ms = round((time.perf_counter() - started) * 1000, 2)

    # 도구 서버가 원래 남기는 기록: 서비스 계정만 보입니다
    print(f"[tool-server] account={SERVICE_ACCOUNT} tool={tool} status={status}", flush=True)

    if AUDIT:
        with seq_lock:
            seq_by_run[run_id] = seq_by_run.get(run_id, 0) + 1
            seq = seq_by_run[run_id]
        index_audit({
            "@timestamp": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
            "service_account": SERVICE_ACCOUNT,
            "agent_id": agent_id,
            "session_id": session_id,
            "run_id": run_id,
            "seq": seq,
            "tool": tool,
            "risk": TOOLS[tool][1] if tool in TOOLS else "unknown",
            "args_summary": summarize(args),
            "approval": approval,
            "status": status,
            "duration_ms": duration_ms,
        })
    return jsonify(result), code


if __name__ == "__main__":
    seed_sandbox()
    app.run(host="0.0.0.0", port=8000)
```

`index_template.json` 은 필드를 키워드로 고정해 집계와 정확 일치 검색이 되도록 하는 색인 템플릿입니다. `agent-alerts` 색인도 같은 템플릿을 씁니다.

```json
{
  "index_patterns": ["agent-audit*", "agent-alerts*"],
  "template": {
    "settings": { "number_of_shards": 1, "number_of_replicas": 0 },
    "mappings": {
      "dynamic_templates": [
        { "strings_as_keyword": { "match_mapping_type": "string", "mapping": { "type": "keyword" } } }
      ],
      "properties": {
        "@timestamp": { "type": "date" },
        "seq": { "type": "integer" },
        "duration_ms": { "type": "float" },
        "args_summary": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }
      }
    }
  }
}
```

`setup.py` 는 템플릿을 넣고 Dashboards 에 인덱스 패턴, 저장된 검색 세 개, 시각화 하나를 만듭니다. 화면에서 Dashboards Management 와 Discover, Visualize 메뉴로 만드는 것과 같은 일이며, 여러 번 실행해도 같은 ID 를 덮어씁니다.

```python
"""인덱스 템플릿을 넣고, Dashboards 에 인덱스 패턴·저장된 검색·시각화를 만듭니다."""
import json
import urllib.request

OS = "http://127.0.0.1:5740"
DASH = "http://127.0.0.1:5741"


def call(method, url, body=None, headers=None):
    data = json.dumps(body).encode() if body is not None else None
    h = {"Content-Type": "application/json", "osd-xsrf": "true"}
    h.update(headers or {})
    req = urllib.request.Request(url, data, h, method=method)
    return json.load(urllib.request.urlopen(req))


with open("index_template.json", encoding="utf-8") as f:
    print("template", call("PUT", f"{OS}/_index_template/agent-logs", json.load(f)))


def saved(kind, obj_id, attributes, references):
    url = f"{DASH}/api/saved_objects/{kind}/{obj_id}?overwrite=true"
    res = call("POST", url, {"attributes": attributes, "references": references})
    print(kind, res["id"])


def index_ref(pattern_id):
    return [{"name": "kibanaSavedObjectMeta.searchSourceJSON.index", "type": "index-pattern", "id": pattern_id}]


def source(query):
    return json.dumps({
        "indexRefName": "kibanaSavedObjectMeta.searchSourceJSON.index",
        "query": {"language": "kuery", "query": query},
        "filter": [],
    })


for pattern in ("agent-audit", "agent-alerts"):
    saved("index-pattern", pattern, {"title": pattern, "timeFieldName": "@timestamp"}, [])

COLUMNS = ["agent_id", "run_id", "seq", "tool", "args_summary", "approval", "status"]

saved("search", "risky-calls", {
    "title": "위험 도구 호출", "description": "", "hits": 0, "columns": COLUMNS,
    "sort": [["@timestamp", "desc"]], "version": 1,
    "kibanaSavedObjectMeta": {"searchSourceJSON": source("risk:high")},
}, index_ref("agent-audit"))

saved("search", "run-ops-01", {
    "title": "run-ops-01 호출 순서", "description": "", "hits": 0, "columns": COLUMNS,
    "sort": [["@timestamp", "asc"]], "version": 1,
    "kibanaSavedObjectMeta": {"searchSourceJSON": source('run_id:"run-ops-01"')},
}, index_ref("agent-audit"))

saved("search", "alerts", {
    "title": "승인 없는 삭제 경고", "description": "", "hits": 0,
    "columns": ["rule", "severity", "agent_id", "run_id", "args_summary"],
    "sort": [["@timestamp", "desc"]], "version": 1,
    "kibanaSavedObjectMeta": {"searchSourceJSON": source("*")},
}, index_ref("agent-alerts"))

axis = {"id": "ValueAxis-1", "name": "LeftAxis-1", "type": "value", "position": "left", "show": True, "style": {},
        "scale": {"type": "linear", "mode": "normal"}, "labels": {"show": True, "rotate": 0, "filter": False, "truncate": 100},
        "title": {"text": "Count"}}
vis_state = {
    "title": "도구별 호출 수", "type": "histogram",
    "aggs": [
        {"id": "1", "enabled": True, "type": "count", "schema": "metric", "params": {}},
        {"id": "2", "enabled": True, "type": "terms", "schema": "segment",
         "params": {"field": "tool", "size": 5, "order": "desc", "orderBy": "1", "otherBucket": False, "missingBucket": False}},
        {"id": "3", "enabled": True, "type": "terms", "schema": "group",
         "params": {"field": "agent_id", "size": 5, "order": "desc", "orderBy": "1", "otherBucket": False, "missingBucket": False}},
    ],
    "params": {
        "type": "histogram", "grid": {"categoryLines": False},
        "categoryAxes": [{"id": "CategoryAxis-1", "type": "category", "position": "bottom", "show": True, "style": {},
                          "scale": {"type": "linear"}, "labels": {"show": True, "truncate": 100}, "title": {}}],
        "valueAxes": [axis],
        "seriesParams": [{"show": True, "type": "histogram", "mode": "stacked", "data": {"label": "Count", "id": "1"},
                          "valueAxis": "ValueAxis-1", "drawLinesBetweenPoints": True, "showCircles": True}],
        "addTooltip": True, "addLegend": True, "legendPosition": "right", "times": [], "addTimeMarker": False,
        "labels": {"show": True}, "thresholdLine": {"show": False, "value": 10, "width": 1, "style": "full", "color": "#E7664C"},
    },
}
saved("visualization", "calls-by-tool", {
    "title": "도구별 호출 수", "visState": json.dumps(vis_state), "uiStateJSON": "{}", "description": "", "version": 1,
    "kibanaSavedObjectMeta": {"searchSourceJSON": json.dumps({
        "indexRefName": "kibanaSavedObjectMeta.searchSourceJSON.index",
        "query": {"language": "kuery", "query": ""}, "filter": []})},
}, index_ref("agent-audit"))
```

`calls.py` 는 에이전트 두 개가 번갈아 도구를 부르는 호출 스크립트입니다. 같은 실행(`run_id`)의 호출 사이에 다른 에이전트의 호출이 끼어 있어, 시간순으로만 보면 섞여 보입니다. `mail-bot` 의 삭제 한 건에만 승인 번호를 붙였습니다. 메일 본문에는 마스킹을 확인할 수 있게 `api_key=` 문구를 넣었습니다.

```python
"""에이전트 두 개(mail-bot, ops-bot)가 번갈아 도구를 호출합니다. 모델 호출은 없습니다."""
import json
import sys
import time
import urllib.error
import urllib.request

PROXY = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:5742"

MAIL = ("mail-bot", "sess-m1")
OPS = ("ops-bot", "sess-o1")

# (에이전트, 실행 ID, 도구, 인자, 승인 번호)
STEPS = [
    (MAIL, "run-mail-01", "read_file", {"path": "report.txt"}, None),
    (OPS, "run-ops-01", "read_file", {"path": "old-backup.txt"}, None),
    (MAIL, "run-mail-01", "send_mail", {"to": "alice", "subject": "3분기 보고서", "body": "초안입니다. api_key=sk-test-12345"}, None),
    (OPS, "run-ops-01", "delete_file", {"path": "old-backup.txt"}, None),
    (MAIL, "run-mail-02", "delete_file", {"path": "notes.txt"}, "CHG-1042"),
    (OPS, "run-ops-01", "read_file", {"path": "missing.txt"}, None),
    (OPS, "run-ops-02", "read_file", {"path": "report.txt"}, None),
    (MAIL, "run-mail-02", "send_mail", {"to": "carol", "subject": "정리 완료", "body": "메모를 정리했습니다."}, None),
    (OPS, "run-ops-02", "delete_file", {"path": "report.txt"}, None),
]

for (agent, session), run, tool, args, approval in STEPS:
    headers = {"Content-Type": "application/json", "X-Agent-Id": agent, "X-Session-Id": session, "X-Run-Id": run}
    if approval:
        headers["X-Approval-Id"] = approval
    req = urllib.request.Request(f"{PROXY}/tools/{tool}", json.dumps({"args": args}).encode(), headers, method="POST")
    try:
        code = urllib.request.urlopen(req).status
    except urllib.error.HTTPError as exc:
        code = exc.code
    print(f"{agent:9} {run:11} {tool:12} HTTP {code}")
    time.sleep(0.4)
```

`query_run.py` 는 `run_id` 하나의 호출을 순서대로 보여 주고, `detect_unapproved_delete.py` 는 승인 없는 삭제를 찾아 경고 문서를 만듭니다. 두 파일은 6절과 7절에서 설명합니다.

```python
"""run_id 하나의 호출을 순서대로 다시 구성해 출력합니다."""
import json
import sys
import urllib.request

OS = "http://127.0.0.1:5740"
run_id = sys.argv[1]
query = {"size": 50, "sort": [{"@timestamp": "asc"}], "query": {"term": {"run_id": run_id}}}
req = urllib.request.Request(f"{OS}/agent-audit/_search", json.dumps(query).encode(), {"Content-Type": "application/json"})
for hit in json.load(urllib.request.urlopen(req))["hits"]["hits"]:
    d = hit["_source"]
    print(f'{d["seq"]}. {d["agent_id"]} {d["tool"]:12} {d["status"]:5} approval={d["approval"]:8} {d["args_summary"]}')
```

```python
"""규칙: delete_file 이 승인 번호 없이 호출되면 agent-alerts 에 경고 문서를 만듭니다."""
import json
import urllib.error
import urllib.request

OS = "http://127.0.0.1:5740"

QUERY = {
    "size": 100,
    "query": {"bool": {"filter": [
        {"term": {"tool": "delete_file"}},
        {"term": {"status": "ok"}},
        {"term": {"approval": "none"}},
    ]}},
}


def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(OS + path, data, {"Content-Type": "application/json"}, method=method)
    return json.load(urllib.request.urlopen(req))


created = 0
for hit in call("POST", "/agent-audit/_search", QUERY)["hits"]["hits"]:
    d = hit["_source"]
    alert = {
        "@timestamp": d["@timestamp"],
        "rule": "unapproved-delete",
        "severity": "high",
        "agent_id": d["agent_id"],
        "session_id": d["session_id"],
        "run_id": d["run_id"],
        "tool": d["tool"],
        "args_summary": d["args_summary"],
        "audit_doc_id": hit["_id"],
    }
    try:  # 감사 문서 ID 를 경고 ID 로 써서 다시 실행해도 중복되지 않게 합니다
        call("PUT", f"/agent-alerts/_create/{hit['_id']}?refresh=true", alert)
        created += 1
    except urllib.error.HTTPError as exc:
        if exc.code != 409:
            raise
print(f"경고 {created}건 생성")
```

## 1. 발견: 서버 로그에 에이전트가 없다

먼저 감사 기록을 끄고(`AUDIT=0`) 도구 서버를 평소처럼 띄웁니다. 에이전트 두 개(`mail-bot`, `ops-bot`)가 서비스 계정 하나로 도구를 번갈아 부릅니다.

```bash
AUDIT=0 docker compose up -d
python calls.py
docker logs cr-t11-proxy 2>&1 | grep tool-server
```

`calls.py` 는 두 에이전트의 호출 아홉 건을 번갈아 보냅니다. 서버가 남긴 기록은 다음과 같습니다.

```text
[tool-server] account=svc-agent tool=read_file status=ok
[tool-server] account=svc-agent tool=read_file status=ok
[tool-server] account=svc-agent tool=send_mail status=ok
[tool-server] account=svc-agent tool=delete_file status=ok
[tool-server] account=svc-agent tool=delete_file status=ok
[tool-server] account=svc-agent tool=read_file status=error
[tool-server] account=svc-agent tool=read_file status=ok
[tool-server] account=svc-agent tool=send_mail status=ok
[tool-server] account=svc-agent tool=delete_file status=ok
```

![도구 서버 로그의 아홉 줄이 모두 같은 서비스 계정이고, 삭제 호출이 세 번 있어도 어느 에이전트의 것인지 알 수 없는지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/01-감사공백-도구-서버-로그.png)

삭제는 세 번 일어났지만 로그만으로는 어느 에이전트가, 어떤 실행에서, 무엇을 지웠는지 알 수 없습니다. 오류 한 건도 마찬가지입니다. 사고가 났을 때 되짚을 단서가 없다는 뜻입니다.

## 2. 원인: 계정이 호출자를 가린다

원인은 두 가지입니다.

- **서비스 계정 공유**: 도구 서버는 연결한 계정만 압니다. 에이전트 둘이 같은 계정을 쓰면 서버 입장에서는 같은 호출자입니다.
- **상관 ID 부재**: 한 번의 에이전트 실행이 만든 호출들을 묶을 값이 없어서, 여러 실행이 섞이면 순서를 되살릴 수 없습니다. 위 기록에서 `read_file` 다음에 `delete_file` 이 나왔다고 해서 같은 실행의 두 단계라고 볼 수도 없습니다.

OWASP Top 10 for LLM Applications 2025의 LLM06 Excessive Agency는 영향이 큰 동작을 사람 확인 없이 실행하게 두는 경우를 원인 중 하나로 꼽습니다. 그런 동작을 찾으려면 먼저 누가 호출했는지가 기록되어야 합니다.

## 3. 수정: 상관 ID 를 헤더로 받아 구조화 로그로 남기기

수정은 도구 서버 앞에서 호출을 받는 프록시에서 합니다. 에이전트 런타임은 호출마다 세 값을 헤더로 붙입니다.

- **`X-Agent-Id`**: 호출한 에이전트의 이름입니다.
- **`X-Session-Id`**: 사용자와의 대화 같은 긴 작업 단위를 가리킵니다.
- **`X-Run-Id`**: 한 번의 실행(요청 하나를 처리하는 단위)을 가리키는 상관 ID 입니다.

삭제처럼 사람의 승인이 필요한 호출에는 `X-Approval-Id` 로 승인 번호를 붙입니다. 프록시는 도구를 실행한 뒤 다음 값을 JSON 한 건으로 만들어 OpenSearch 에 색인합니다.

| 필드 | 내용 |
|------|------|
| `agent_id`, `session_id`, `run_id` | 누가, 어느 세션에서, 어느 실행에서 |
| `seq` | 같은 `run_id` 안의 호출 순번(프록시가 센 값) |
| `tool`, `risk` | 도구 이름과 위험도(low, medium, high) |
| `args_summary` | 인자 요약. 이름에 `key`, `token`, `pass` 등이 들어간 인자는 `***`, 값에 `api_key=...` 같은 문구가 있으면 `api_key=***`, 60자 초과는 잘라냄 |
| `approval` | 승인 번호, 없으면 `none` |
| `status`, `duration_ms` | `ok` 또는 `error`, 처리 시간 |
| `service_account` | 도구 서버가 보던 계정. 원래 기록과 맞춰 보려고 남김 |

색인에 실패해도 도구 호출은 막지 않고 오류만 출력하도록 만들었습니다. 감사 저장소 장애가 업무를 멈추게 할지는 정책 문제이며, 실패 시 호출을 막는 쪽(fail closed)으로 바꿀 수도 있습니다.

감사 기록을 켜서 다시 시작합니다. 템플릿과 Dashboards 설정을 먼저 넣고, 프록시를 다시 만들면서 `/data` 의 실습 파일도 처음 상태로 되돌립니다. Dashboards 는 뜨는 데 1분쯤 걸리므로, `setup.py` 가 연결 오류로 끝나면 잠시 뒤 다시 실행합니다.

```bash
docker compose up -d
python setup.py
docker rm -f cr-t11-proxy
docker compose up -d proxy
docker compose ps --format '{{.Service}} {{.Status}}'
```

```text
template {'acknowledged': True}
index-pattern agent-audit
index-pattern agent-alerts
search risky-calls
search run-ops-01
search alerts
visualization calls-by-tool
```

`docker compose up -d` 를 처음 실행하면 이미지를 내려받느라 시간이 걸립니다. 1절에서 `AUDIT=0` 으로 띄운 프록시는 `docker rm -f cr-t11-proxy` 로 지우고 다시 만들어야 감사 기록이 켜집니다. 1절의 삭제로 `/data` 의 파일이 없어졌으므로, 같은 호출이 같은 결과를 내도록 실습 파일을 처음 상태로 되돌리는 단계이기도 합니다.

## 4. 재확인: 같은 호출을 다시 보내고 문서 확인하기

같은 호출 스크립트를 한 번 더 실행합니다.

```bash
python calls.py
```

```text
mail-bot  run-mail-01 read_file    HTTP 200
ops-bot   run-ops-01  read_file    HTTP 200
mail-bot  run-mail-01 send_mail    HTTP 200
ops-bot   run-ops-01  delete_file  HTTP 200
mail-bot  run-mail-02 delete_file  HTTP 200
ops-bot   run-ops-01  read_file    HTTP 400
ops-bot   run-ops-02  read_file    HTTP 200
mail-bot  run-mail-02 send_mail    HTTP 200
ops-bot   run-ops-02  delete_file  HTTP 200
```

400 은 `missing.txt` 가 없어서 난 의도한 오류입니다. 메일 호출 문서 하나를 꺼내 봅니다.

```bash
curl -s '127.0.0.1:5740/agent-audit/_search?q=run_id:run-mail-01+AND+tool:send_mail&size=1&filter_path=hits.hits._source&pretty'
```

```json
{
  "hits" : {
    "hits" : [
      {
        "_source" : {
          "@timestamp" : "(실행한 시각)",
          "service_account" : "svc-agent",
          "agent_id" : "mail-bot",
          "session_id" : "sess-m1",
          "run_id" : "run-mail-01",
          "seq" : 2,
          "tool" : "send_mail",
          "risk" : "medium",
          "args_summary" : "body=초안입니다. api_key=***, subject=3분기 보고서, to=alice",
          "approval" : "none",
          "status" : "ok",
          "duration_ms" : 0.1
        }
      }
    ]
  }
}
```

`@timestamp` 와 `duration_ms` 는 실행할 때마다 값이 다릅니다.

![감사 문서에 agent_id 와 run_id 가 들어 있고, 본문에 있던 api_key 값이 별표로 가려져 있는지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/02-마스킹된-감사-문서.png)

서비스 계정은 그대로 `svc-agent` 이지만, 이제 `mail-bot`, `sess-m1`, `run-mail-01` 이 함께 남습니다. 본문에 있던 `sk-test-12345` 는 색인에 들어가지 않았습니다.

## 5. Dashboards 에서 위험 도구 호출 보기

Dashboards 는 `http://localhost:5741` 에서 열립니다. 보안 플러그인을 꺼 두었으므로 로그인 화면이 없습니다. `setup.py` 가 만든 저장된 검색을 Discover 에서 엽니다. 방금 넣은 로그가 보이도록 시간 범위를 지정한 주소입니다.

```text
http://localhost:5741/app/data-explorer/discover#/view/risky-calls?_g=(time:(from:now-30m,to:now))
```

검색어는 `risk:high` 입니다. 위험도가 높은 도구인 `delete_file` 호출만 남으며, 여기서 `agent_id`, `run_id`, `approval` 열을 함께 봅니다.

![Discover 에서 risk:high 로 삭제 호출 3건이 나오고, ops-bot 의 두 건은 approval 이 none, mail-bot 의 한 건은 CHG-1042 인지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/03-discover-위험-호출.png)

1절에서는 삭제 세 건을 구분할 수 없었지만, 이제 두 건은 `ops-bot` 이 승인 없이, 한 건은 `mail-bot` 이 승인 번호 `CHG-1042` 와 함께 지웠다는 것을 알 수 있습니다. 화면의 시각은 브라우저의 시간대로 표시되므로 한국 시간대에서는 문서의 UTC 시각보다 9시간 늦은 시각으로 보입니다.

도구별 호출 수는 시각화로 봅니다. `http://localhost:5741/app/visualize#/edit/calls-by-tool?_g=(time:(from:now-30m,to:now))` 를 엽니다. 가로축은 `tool`, 쌓은 막대는 `agent_id` 입니다.

![막대 그래프에서 read_file 이 4건(ops-bot 3, mail-bot 1), delete_file 이 3건, send_mail 이 2건으로 나오는지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/05-시각화-도구별-호출.png)

## 6. run_id 로 호출 순서 재구성하기

섞여 있던 호출을 `run_id` 로 다시 모읍니다. `ops-bot` 의 `run-ops-01` 만 시간순으로 봅니다. 저장된 검색 `run-ops-01` 은 `run_id:"run-ops-01"` 검색에 시간 오름차순 정렬을 건 것입니다.

```text
http://localhost:5741/app/data-explorer/discover#/view/run-ops-01?_g=(time:(from:now-30m,to:now))
```

![Discover 에서 run-ops-01 의 세 호출이 읽기, 삭제, 없는 파일 읽기 오류 순으로 나오고 seq 가 1, 2, 3 인지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/04-discover-run-순서.png)

실행 한 번이 `old-backup.txt` 를 읽고, 지우고, 이어서 없는 파일을 읽다 오류를 낸 과정이 한눈에 보입니다. 같은 일을 터미널에서 하는 것이 `query_run.py` 입니다. 실행 두 개를 확인하고 승인이 붙은 삭제가 어떻게 보이는지도 봅니다.

```bash
python query_run.py run-ops-01
python query_run.py run-mail-02
```

```text
1. ops-bot read_file    ok    approval=none     path=old-backup.txt
2. ops-bot delete_file  ok    approval=none     path=old-backup.txt
3. ops-bot read_file    error approval=none     path=missing.txt
1. mail-bot delete_file  ok    approval=CHG-1042 path=notes.txt
2. mail-bot send_mail    ok    approval=none     body=메모를 정리했습니다., subject=정리 완료, to=carol
```

## 7. 규칙 하나: 승인 없는 삭제에 경고 만들기

규칙은 "`delete_file` 이 성공했는데 승인 번호가 `none` 이면 경고"입니다. 쿼리로 쓰면 다음과 같습니다. 필터 조건 세 개를 모두 만족하는 감사 문서가 대상입니다.

```json
{"query": {"bool": {"filter": [
  {"term": {"tool": "delete_file"}},
  {"term": {"status": "ok"}},
  {"term": {"approval": "none"}}
]}}}
```

`detect_unapproved_delete.py`(앞에서 저장한 파일)는 이 쿼리의 결과마다 `agent-alerts` 색인에 경고 문서를 만듭니다. 경고 문서의 ID 를 원본 감사 문서의 ID 로 정해, 다시 실행해도 같은 경고가 중복되지 않습니다. 이 글에서는 직접 실행했지만 같은 쿼리를 OpenSearch Alerting 의 모니터에 넣거나 주기 실행으로 돌려도 됩니다.

```bash
python detect_unapproved_delete.py
python detect_unapproved_delete.py
```

```text
경고 2건 생성
경고 0건 생성
```

첫 실행에서 `ops-bot` 의 삭제 두 건이 경고가 되고, 승인 번호가 있는 `mail-bot` 의 삭제는 제외됩니다. 두 번째 실행은 이미 만든 경고를 다시 만들지 않아 0건입니다. 경고도 Discover 의 저장된 검색으로 볼 수 있습니다.

```text
http://localhost:5741/app/data-explorer/discover#/view/alerts?_g=(time:(from:now-30m,to:now))
```

![승인 없는 삭제 경고 2건이 rule 이 unapproved-delete, severity 가 high, agent_id 가 ops-bot 으로 나오고 run_id 로 원본 실행을 찾을 수 있는지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/06-discover-경고.png)

경고에 `run_id` 가 들어 있으므로 6절의 방법으로 그 실행의 앞뒤 호출을 바로 열 수 있습니다.

![터미널에서 run 재구성 결과와 경고 생성 결과가 Dashboards 화면과 같은 내용으로 나오는지 확인합니다.](https://copyandrun.com/img/llm-agent-audit-log-opensearch/07-run-재구성과-경고-생성.png)

## 자주 막히는 곳

**`setup.py` 가 연결 오류로 끝남**: Dashboards 가 아직 뜨지 않았습니다. 1분쯤 뒤 다시 실행합니다. 같은 ID 를 덮어쓰므로 여러 번 실행해도 됩니다.

**Discover 에 결과가 없음**: 시간 범위가 로그를 받은 시각을 포함하지 않는 경우입니다. 주소의 `from:now-30m` 을 늘리거나 호출 스크립트를 다시 실행합니다.

**삭제 호출이 `HTTP 400`**: 프록시를 다시 만들지 않고 `calls.py` 를 두 번째 실행하면 이미 지운 파일을 또 지우려다 오류가 납니다. `docker rm -f cr-t11-proxy` 와 `docker compose up -d proxy` 로 실습 파일을 되돌립니다.

**OpenSearch 컨테이너가 바로 종료됨**: 메모리 또는 `vm.max_map_count` 부족인 경우가 많습니다. `docker compose logs opensearch` 로 종료 사유를 먼저 봅니다.

## 정리

실습이 끝나면 컨테이너와 볼륨을 지웁니다.

```bash
docker compose down -v
```

## 이어서 해 볼 것

- **차단으로 확장**: 이 글의 규칙은 호출을 막지 않고 알리기만 합니다. 프록시에서 `delete_file` 에 승인 번호가 없으면 403 으로 거절하는 쪽으로 바꾸고, 거절한 호출도 감사 문서로 남겨 봅니다.
- **헤더 위조 막기**: 지금은 호출자가 보낸 헤더를 그대로 믿습니다. 에이전트마다 서로 다른 토큰을 발급해 프록시가 토큰에서 `agent_id` 를 정하게 하면 에이전트가 다른 에이전트인 척할 수 없습니다.
- **보존과 접근**: 감사 색인은 일반 로그보다 오래 보관하고, 수정과 삭제 권한을 에이전트 계정에서 분리합니다. 이 글의 실습 구성은 보안 플러그인을 꺼 두어 이 부분을 다루지 않았습니다.
- **인자 마스킹 점검**: 이 글의 마스킹은 인자 이름과 `api_key=` 같은 문구만 봅니다. 이메일 주소나 주민등록번호 같은 값은 따로 규칙을 추가해야 합니다.

## 확인 범위

- **해 본 것:** Windows Docker Desktop에서 OpenSearch 3.2.0, OpenSearch Dashboards 3.2.0, `python:3.12-slim`(Flask 3.1.3)을 띄웠습니다. 호스트 Python 3.12.10으로 위 파일을 실행하여 인용한 출력과 화면을 확인했습니다. `docker stats`에서 OpenSearch 컨테이너는 한도 1GiB 안에서 동작했습니다. 호스트 포트(5740, 5741, 5742)는 실행한 값 그대로입니다.
- **해 보지 않은 것:** OpenSearch Alerting 모니터, Linux와 Mac, 3.2.0 이외 버전, 실제 LLM이 도구를 호출하는 구성은 확인하지 않았습니다.
- **읽을 때 주의:** 에이전트가 헤더를 직접 보낸다고 가정한 구성입니다. 실제 에이전트 프레임워크에서 헤더를 붙이는 방법은 쓰는 프레임워크의 문서를 확인합니다.
