문제점

Claude Code(그리고 다른 모든 AI 코딩 CLI)는 전체 대화 기록을 디스크에 평문 JSONL로 저장합니다. Claude Code는 ~/.claude/projects/ 아래에, OpenAI Codex는 ~/.codex/sessions/ 아래에 저장합니다. AWS 키, .env 파일, 데이터베이스 URL 등 무엇을 붙여넣든 평문으로 무기한 남아 있습니다. 일반적인 개발자의 기록에는 몇 달에 걸쳐 수십 개의 시크릿이 쌓이는데, 대개 눈치채지 못합니다.

agentsweep은 그 기록을 스캔하여 무엇이 유출되었는지 알려주고, JSONL 구조를 바이트 단위로 보존하면서 시크릿 값을 제자리에서 삭제할 수 있습니다. 또한 각 제공업체에 맞는 올바른 폐기 URL과 함께 어떤 키를 교체해야 하는지 알려줍니다.

보호 범위: agentsweep은 완전히 로컬이며 오프라인입니다. 여러분의 컴퓨터에 있는 파일만 읽고 쓰며 네트워크 호출을 전혀 하지 않습니다. 이는 하나의 공격 벡터, 즉 로컬 기록 파일에 남아 있는 시크릿을 제거합니다. AI 제공업체가 이미 수신한 내용에는 영향을 미치지 않습니다. Claude Code, Cursor 또는 클라우드 기반 에이전트에 키를 붙여넣으면, 그 키는 디스크에 닿기 전에 이미 제공업체의 서버를 거쳐갔습니다. 이것이 걱정된다면 아무것도 컴퓨터를 떠나지 않는 로컬 호스팅 모델(Ollama, LM Studio, OpenCode)을 고려하세요. 이는 agentsweep과 잘 어울립니다.

지금 이게 중요한 이유

공급망 공격이 가속화되고 있습니다. 2024년과 2025년에 악성 npm 및 PyPI 패키지 물결(sha256-universal, shailulid, 수백 개의 타이포스쿼트)이 이를 설치한 컴퓨터에서 개발자 자격 증명을 유출하는 것이 적발되었습니다. 이들은 환경 변수, .env 파일, 셸 기록, SSH 키, 그리고 이제는 AI 에이전트 기록 파일을 노립니다.

AI 코딩 어시스턴트는 2년 전에는 존재하지 않았던 새로운 범주의 자격 증명 노출을 만들어냈습니다:

• 디버깅을 위해 프로덕션 API 키를 Claude Code에 붙여넣음 → 이제 ~/.claude/projects/*/conversations/*.jsonl에 영원히 남음
• 손상된 npm 패키지가 postinstall을 실행 → 일반적인 경로를 스캔 → JSONL 기록을 발견 → 한 번의 요청으로 50개의 API 키를 유출
• 공개적으로 사용한 키는 교체했지만 기록에 있는 다른 수십 개는 잊어버림
• 그동안 기록은 계속 쌓임: AI에게 도움을 요청한 모든 .env, 디버깅을 위해 공유한 모든 DB URL, 한 줄짜리 명령을 위해 붙여넣은 모든 토큰

AI 에이전트 기록은 셸 기록이 보관하는 명령뿐 아니라 전체 컨텍스트를 담고 있습니다. 공격자들은 이미 이를 스캔하고 있습니다. agentsweep은 그런 일이 벌어지기 전에 기록을 정리합니다.

빠른 시작

pip install uv                  # get uv (skip if you already have it)
uv tool install agentsweep      # install — adds `agentsweep` and `asweep` to PATH
asweep                          # run — interactive menu guides you through everything

가상환경을 활성화할 필요도, PATH를 조작할 필요도 없습니다. uv tool install은 해당 명령에 자체적인 격리 환경을 제공합니다.

작동 방식

agentsweep은 고정된 5단계 파이프라인을 실행합니다. scan은 3단계에서 멈추고, fix는 리댁션까지 계속 진행합니다.

flowchart LR
    A("🔍 DISCOVER\nwalk history dirs\nstream file list") --> B("⚡ SCAN\nAho-Corasick pre-filter\n207 regex rules + BIP-39")
    B --> C{"secrets\nfound?"}
    C -- "none" --> D("✅ CLEAN\nexit 0")
    C -- "found" --> E("📋 FINDINGS\nshow report\nexit 1")
    E -. "scan only" .-> F("⚠️ ROTATE\nkeys still live")
    E -- "type REDACT" --> G("✏️ REDACT\natomic write · .bak backup\npost-write JSON validation")
    G --> H("🔑 ROTATE\nper-provider\nrevocation links")

    style A fill:#1e3a5f,color:#fff,stroke:#2d5986
    style B fill:#1e3a5f,color:#fff,stroke:#2d5986
    style C fill:#4a3728,color:#fff,stroke:#7a5c3f
    style D fill:#1a4731,color:#fff,stroke:#2d7a52
    style E fill:#4a3a1e,color:#fff,stroke:#7a6030
    style F fill:#4a2020,color:#fff,stroke:#8b3a3a
    style G fill:#1e3a5f,color:#fff,stroke:#2d5986
    style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b

여덟 가지 안전 불변 조건이 모든 쓰기를 보호합니다: 원자적 교체, 필수 .bak 백업, 심볼릭 링크 거부, mtime 및 프로세스 게이트, 그리고 쓰기 후 JSONL 검증입니다. agentsweep undo는 백업에서 복원합니다.

설치

agentsweep은 명령줄 도구이므로 자체 격리된 환경에 설치하세요. 두 가지 권장 옵션 모두 이를 설정합니다.

uv (권장):

uv tool install agentsweep      # install
uv tool upgrade agentsweep      # update
uvx agentsweep@latest           # or run once without installing

선택적 네이티브 가속

기본 설치는 이식성이 뛰어나며 Python 내장 re 엔진을 사용합니다. google-re2 휠이 있는 플랫폼에서는 선택적 fast 추가 기능을 설치하여 혼합 엔진을 사용할 수 있습니다:

uv tool install 'agentsweep[fast]'
# or, in a virtual environment:
pip install 'agentsweep[fast]'

이는 가속 전용입니다: 지원되지 않는 패턴, 비-ASCII 의미론적 엣지 케이스, 짧은 문자열, 그리고 매우 밀집된 매치는 정확한 Python re 경로를 유지합니다. 선택적 wheel을 사용할 수 없는 경우에도 AgentSweep은 완전히 정상 동작합니다. 성능 노트와 호환성 감사를 참조하세요.

pipx:

pipx install agentsweep
pipx upgrade agentsweep

pip도 작동하지만, 가상 환경 안에서 사용하세요. 최신 Linux와 macOS는 시스템 Python에 pip install을 차단하며(PEP 668), CLI는 어차피 거기에 있을 이유가 없습니다:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install agentsweep

conda는 필요하지 않습니다. conda는 무거운 바이너리 및 과학 스택을 위해 존재하며, agentsweep은 세 개의 작은 의존성만 가진 순수 Python입니다.

Android (Termux):

pkg install python clang
pip install agentsweep

clang 패키지를 사용하면 네이티브 의존성 하나가 Android의 libc에 대해 빌드됩니다.

uv가 없나요? pip install uv를 실행하거나 astral.sh/uv를 참고하세요. Python 3.11+가 필요합니다.

Docker

리포지토리 루트에서 이미지를 빌드합니다:

docker build -t agentsweep .

agentsweep은 소스의 히스토리 루트(예: ~/.claude) 아래의 파일들을 스캔하므로, 실제 홈 디렉터리(또는 관련 에이전트 폴더만)를 컨테이너에 마운트하고 --root를 그곳으로 지정하세요. -u $(id -u):$(id -g)는 마운트에 다시 쓰이는 파일 (예: .bak 백업)이 root가 아닌 사용자 소유가 되도록 유지합니다:

docker run --rm -it -u $(id -u):$(id -g) \
  -v "$HOME/.claude:/home/sweeper/.claude:rw" \
  agentsweep scan --source claude-code