문제

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 에이전트 기록은 새로운 .bash_history입니다. 단, 명령어뿐만 아니라 전체 컨텍스트를 포함합니다. 공격 도구는 이미 이를 알고 있습니다. agentsweep은 악용되기 전에 정리하기 위해 존재합니다.

빠른 시작

pip install uv                  # uv 설치 (이미 있다면 건너뜀)
uv tool install agentsweep      # 설치 — `agentsweep` 및 `asweep`을 PATH에 추가
asweep                          # 실행 — 대화형 메뉴가 모든 것을 안내

이것으로 끝입니다. 가상 환경을 활성화하거나 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\n191 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

모든 쓰기는 8개의 안전 불변 조건으로 보호됩니다. 원자적 교체, 필수 .bak 백업, 심볼릭 링크 거부, mtime/프로세스 게이트, 쓰기 후 JSONL 검증. agentsweep undo는 백업에서 복원합니다.

설치

권장 — 격리, venv 충돌 없음:

uv tool install agentsweep      # 일회성 설치
uv tool upgrade agentsweep      # 최신 버전으로 업데이트

설치 없이 시도 (항상 최신 버전 실행):

uvx agentsweep@latest

클래식 pip:

pip install agentsweep
pip install --upgrade agentsweep

uv가 없습니까? pip install uv 또는 astral.sh/uv를 참조하십시오. Python 3.11+가 필요합니다.

사용법

대화형 모드

터미널에서 인수 없이 실행하면 전체 경험이 제공됩니다. 배너, 번호가 매겨진 메뉴, 파괴적인 작업 전에 입력 확인, 한 키로 취소(.bak 백업 복원). 비밀 정보를 찾은 모든 대화형 스캔은 즉시 수정하겠다는 제안으로 끝납니다(REDACT 입력하여 확인).

agentsweep

스크립팅은 영향을 받지 않습니다. 모든 플래그 또는 파이프/리디렉션된 스트림은 메뉴를 완전히 건너뛰고 아래에 문서화된 대로 정확히 작동합니다.

동사

레거시 플래그 형식 agentsweep --fix도 계속 허용되며 agentsweep fix와 동일하게 작동합니다.

소스 선택

--source로 대상 에이전트의 기록을 선택합니다. 기본값은 claude-code입니다.

agentsweep scan --source claude-code          # ~/.claude/projects/ (기본값)
agentsweep scan --source codex                # ~/.codex/sessions/
agentsweep scan --source opencode             # OpenCode SQLite 저장소
agentsweep scan --source cursor               # Cursor 기록
agentsweep scan --source windsurf             # Windsurf 기록
agentsweep scan --source aider                # ~/.aider/
agentsweep scan --source cline                # Cline 기록
agentsweep scan --source gemini-cli           # Gemini CLI 기록
agentsweep scan --source continue-vscode      # Continue (VS Code) 기록
agentsweep scan --source github-copilot-chat  # GitHub Copilot Chat 기록
agentsweep scan --source openclaw             # OpenClaw ~/.openclaw/
agentsweep scan --source hermes               # Hermes Agent ~/.hermes/state.db
agentsweep scan --source goose                # Goose ~/.local/share/goose/

어떤 에이전트가 설치되어 있는지 모르시겠습니까? list-sources는 지원되는 모든 소스, 해당 기록 위치, 그리고 이 머신에 해당 기록이 존재하는지 여부를 출력합니다. 따라서 어떤 --source 값을 스캔할 가치가 있는지 알 수 있습니다. 읽기만 하고 쓰지는 않습니다.

agentsweep list-sources             # 29개 모든 소스 + 디스크에 있는 것
agentsweep list-sources --detected  # 이 머신에서 발견된 것만
agentsweep list-sources --json      # 기계 판독 가능 (스크립트/CI용)

한 번에 모든 등록된 에이전트를 스캔합니다 (통합된 결과, 수정은 소스별로 유지됨):

agentsweep scan --all                 # 모든 등록된 소스
agentsweep scan --all --detected      # 디스크에 기록 루트가 있는 소스만
agentsweep scan --all --json          # 통합 JSON (각 결과에는 "source" 포함)
agentsweep scan --all --json -o out.json

임의의 폴더를 스캔하기 위해 기본 루트 디렉터리를 재정의합니다:

agentsweep scan --root ~/backups/claude-history
agentsweep fix  --root /tmp/history-copy --allow-production

스캔/수정 플래그

# 기계 판독 가능 JSON을 stdout으로 출력 (종료 코드 0 = 깨끗함, 1 = 발견, 2 = 오류)
agentsweep scan --json

# 결과 JSON을 stdout 대신 파일에 저장
agentsweep scan --json -o findings.json
agentsweep scan --json --output /tmp/report.json

# .agentsweepignore 파일 건너뛰기
agentsweep scan --no-ignore

수정 전용 플래그

# Claude Code 기록을 제자리에서 수정 (알파 버전에서는 기본 루트에 --allow-production 필요)
agentsweep fix --allow-production

# .bak 백업 생성 건너뛰기 (권장하지 않음)
agentsweep fix --allow-production --no-backup

# 소프트 안전 검사 우회: mtime 게이트 (60초 미만 전 수정된 파일) 및 실행 중인 프로세스 게이트
agentsweep fix --allow-production --force

# 결합: 비대화형 JSON 모드 수정, 사용자 지정 루트 대상
agentsweep fix --root ~/history-copy --json

Undo 플래그

# 특정 소스에 대한 수정 되돌리기
agentsweep undo --source codex

# 사용자 지정 루트에 대해 되돌리기
agentsweep undo --root ~/history-copy

손상 방지 보장

기록을 손상시키는 수정 도구는 수정하려는 유출보다 훨씬 나쁩니다. agentsweep은 모든 --fix에 대해 다음 불변 조건을 적용합니다.

1. 수정은 원시 바이트가 아닌 파싱된 JSON에서 수행됩니다. 비밀 정보는 파싱된 구조 내에서 문자열 값으로 대체된 후 다시 직렬화됩니다. 구조적 손상은 설계상 불가능합니다.
2. 원자적 쓰기. 모든 재작성은 임시 파일 → fsync() → 원본 위에 os.replace() 순서로 진행됩니다. 어떤 순간에 충돌이 발생해도 완전한 이전 파일 또는 완전한 새 파일만 남게 되며, 찢어진 쓰기는 절대 발생하지 않습니다.
3. 쓰기 후 검증. 커밋하기 전에 새 콘텐츠는 형식을 인식하는 검사를 통과해야 합니다. JSONL — 모든 비어 있지 않은 줄이 JSON으로 파싱되고 줄 수가 원본과 일치해야 함; 전체 파일 JSON — 문서가 파싱됨; 마크다운/일반 텍스트 — 줄 수가 원본과 일치해야 함; SQLite — 다시 작성된 복사본이 PRAGMA integrity_check를 통과해야 함. 검사가 실패하면 쓰기가 중단되고 원본은 그대로 유지됩니다.
4. .bak 백업 기본 제공. 수정 전 비밀 정보를 포함하므로 소유자만 읽을 수 있도록 생성됨 (모드 0600); .bak이 이미 존재하면 실행 거부 (이전 백업을 덮어쓸 수 없도록).
5. 경로 제한. 소스의 기록 트리 중 하나 내부로 확인되지 않는 대상은 거부 (예: Windsurf의 User 디렉토리 및 ~/.codeium/windsurf/memories/).
6. 심볼릭 링크 거부. 심볼릭 링크는 완전히 거부.
7. mtime 창. 지난 60초 이내에 수정된 파일 거부 (활성 세션 가능성). --force로 재정의.
8. 실행 중인 프로세스 확인. Claude Code 프로세스가 실행 중인 것으로 보이면 거부. --force로 재정의.
9. 알파 단계 프로덕션 게이트. 기본 ~/.claude/projects/ 루트에 대한 는 v1.0까지 이 필요합니다.

복구

수정된 모든 파일에는 원본 바이트가 포함된 형제 *.bak 파일이 있습니다. 소스에 대한 모든 수정을 취소하는 가장 쉬운 방법은 다음과 같습니다.

agentsweep undo                        # Claude Code 취소 (기본값)
agentsweep undo --source codex         # 특정 소스 취소
agentsweep undo --root ~/history-copy  # 사용자 지정 루트에 대해 취소

단일 파일을 수동으로 복원해야 하는 경우 (예: undo 명령어 소스를 삭제한 경우):

mv session.jsonl.bak session.jsonl

백업에는 수정 전 원본, 즉 일반 텍스트 비밀 정보가 포함되어 있으므로 유출된 키가 교체되고 백업이 제거될 때까지 정리가 완료되지 않습니다. 키를 교체한 후:

agentsweep purge                       # Claude Code 백업 삭제 (먼저 확인)
agentsweep purge --source windsurf     # 특정 소스 백업 삭제
agentsweep purge --yes                 # 비대화형 (스크립트 / CI)

탐지되는 항목

191개의 높은 신뢰도 패턴 및 체크섬이 검증된 암호화 시드 문구 탐지기 — BIP-39 니모닉 (12/15/18/21/24 단어; BTC, ETH, SOL, BNB, ADA, DOGE, LTC, DOT, AVAX 및 사실상 모든 주요 체인의 지갑 형식) 및 Electrum 시드는 암호화 방식으로 확인되므로 (BIP-39 체크섬 / Electrum 버전 태그) 지갑 단어를 우연히 사용하는 영어 문장은 오탐을 일으키지 않습니다.

패턴: AWS 액세스 키, GitHub 토큰 (PAT/OAuth/앱/세분화), Stripe 라이브/테스트, OpenAI, Anthropic, Google API, Slack 봇/사용자/웹훅, Hugging Face, JWT, PEM 개인 키, 비밀번호가 포함된 DB URL, npm/PyPI/SendGrid/Twilio 토큰 — 또한 GitLab, Grafana, HashiCorp Vault/Terraform, DigitalOcean, Shopify, PlanetScale, Databricks, Atlassian, Azure AD, 1Password, Sentry, New Relic, Mailgun, Datadog, Twilio, Twitter/X, Twitch, Yandex, JFrog, Snyk, Mailchimp, 명령줄의 curl 자격 증명 등을 다루는 gitleaks 팩에서 포팅된 167개 규칙. 패턴은 정밀도가 높습니다. 오탐은 드물며, 제공자 컨텍스트 규칙은 키워드로 게이트되므로 큰 붙여넣기도 빠르게 유지됩니다.

탐지되지 않는 항목

• 인식 가능한 접두사가 없는 사용자 지정/독점 비밀 정보.
• Monero 시드 문구 (Monero 자체 단어 목록의 25단어 — 계획됨).
• 임의의 base64처럼 보이는 알 수 없는 토큰.
• 여러 메시지에 걸쳐 분할된 비밀 정보.
• 바이너리/비 UTF-8 파일 내부의 모든 것.

더 깊은 탐지를 위해 gitleaks 또는 trufflehog를 agentsweep과 함께 실행하십시오. 이들의 규칙 팩이 더 철저합니다. agentsweep의 가치는 탐지 엔진이 아니라 에이전트 기록에 특화된 표면에 있습니다.

FAQ

uvx agentsweep이 이전 버전을 표시하는 이유는 무엇입니까? uvx는 도구를 로컬에 캐시합니다. 항상 최신 버전을 실행하려면 uvx agentsweep@latest를 사용하는 것이 좋습니다. 또는 uvx --reinstall agentsweep으로 캐시를 강제로 새로 고치십시오.

메뉴에서 OpenCode는 어디에 있습니까? OpenCode 지원은 v0.1.1에서 추가되었습니다. pip install --upgrade agentsweep 또는 uvx agentsweep@latest를 실행하여 가져오십시오.

agentsweep이 내 데이터를 어디로 보내나요? 아닙니다. 완전히 오프라인입니다. 스캔 또는 수정 중 네트워크 호출이 전혀 없습니다. 유일한 선택적 네트워크 호출은 백그라운드 업데이트 확인으로, PyPI에서 최신 버전 번호만 가져옵니다.

기여자

코드, 버그 보고서 및 아이디어를 제공한 모든 분들께 감사드립니다.

라이선스

MIT. LICENSE 참조.