Agentguard

AgentGuard

[English](README.en.md)

[](https://www.npmjs.com/package/@pk42ac/agentguard)

Licensed under the [Apache License 2.0](LICENSE).

Codex, Claude Code, Hermes, MCP 설정, 에이전트 트랜스크립트/로그, PR diff를 운영하는 한국 팀을 위한 한국어 우선 AgentOps 보안 스캐너.

AgentGuard는 한국 팀이 에이전트 기반 개발을 운영할 때 노출될 수 있는 비밀 값, 위험한 MCP 권한, 에이전트 셸 동작, PR diff 리스크를 배포 전에 확인하도록 돕습니다. 지금의 한국어 우선 범위는 문서, 정책 설명, 팀 협업 가이드, 기본 터미널/Markdown 리포트입니다. CLI commands, rule IDs, JSON/SARIF/API/machine fields는 CI/CD와 글로벌 보안 도구 연동을 위해 English-compatible, global-standard 계약으로 유지합니다.

v0.3.0부터는 AI 코딩 에이전트 생애주기 보안을 로컬 워크플로로 제공합니다 — 신입 입사자 PC의 설치된 AI 도구·권한을 점검하는 온보딩 인스펙션, 퇴사자 PC의 잔여 자격증명을 훑어 승인 후에만 삭제하고 감사 리포트를 남기는 오프보딩 스윕, 그리고 이를 운영하는 관리자 전용 로컬 터미널 대시보드(agentguard). 이 로컬 워크플로는 대상 PC에서 웹·중앙 서버 없이 오프라인으로 동작하며, 아래 v0.5의 컨트롤 플레인·웹 콘솔은 선택적(opt-in) 하이브리드 SaaS 레이어입니다.

설치

npm install -g @pk42ac/agentguard

빠른 시작

# Scan a repo/workspace (기본 Markdown 리포트는 한국어)
agentguard scan-files .

# 로컬 설치/예제/스캐너 준비 상태 확인
agentguard doctor

# 팀/CI readiness gate용 machine-readable JSON
agentguard doctor --json

# Claude/Codex/Gemini/MCP 로컬 설정의 에이전트 권한 posture 점검
agentguard posture .

# 영어 Markdown 리포트가 필요하면
agentguard scan-files . --lang en

# Scan a PR diff
git diff origin/main...HEAD | agentguard scan-diff

# Emit SARIF for GitHub code scanning
git diff origin/main...HEAD | agentguard scan-diff --sarif --out agentguard.sarif

# Scan Codex/MCP config
agentguard scan-mcp 
  

  
    Agents — 설치된 AI CLI·툴 인벤토리(온보딩 체크)
    Posture — MCP/에이전트 config 과다 권한
  
  
    Baseline — 스냅샷 저장 후 drift 비교
    Offboard — 승인 기반 오프보딩 스윕
  

전체 단축키 오버레이 (?)

  

**CLI 리포트 — `agentguard doctor` · `scan-diff`** (터미널/CI용 Markdown 리포트, 기본 한국어)

  

## 왜 필요한가

AI 코딩 에이전트는 이제 코드베이스, 터미널, GitHub, 데이터베이스, Slack, Drive, 내부 도구에 연결됩니다. 기존 SAST 도구는 애플리케이션 코드를 검사하지만, 다음 질문에는 충분히 답하지 못합니다.

> 에이전트가 무엇을 읽고, 실행하고, 노출하고, 변경하려 했는가?

AgentGuard는 한국어 우선 운영 문서와 정책 설명을 제공하면서도 자동화와 보안 도구가 기대하는 영어 기반 계약은 유지합니다.

## 검사 대상

| Surface | Examples |
|---|---|
| Secrets | OpenAI/Anthropic/GitHub/Google-style tokens, credential-shaped environment values |
| Agent logs | risky shell commands, sensitive paths, unsafe operations visible in transcripts/logs |
| PR diffs | newly-added secrets, PII, dangerous commands, agent policy violations |
| MCP/Codex config | broad filesystem roots, writable paths, credential passthrough, full-access servers |
| Policy files | YAML/JSON policy aliases, malformed policy documents, unsafe duplicates |
| Shell rc keys | `.bashrc`/`.zshrc`/PowerShell `$PROFILE`에 export된 API 키·credential-named 변수 |
| npm global AI CLIs | 전역 설치된 AI 코딩 CLI(Claude Code/Codex/Gemini 등) — 온보딩·오프보딩 신호 |
| AI tool config | `~/.claude`·`~/.codex` 등 잔여 자격증명, Claude Desktop/Cursor MCP config |

## 예시 finding

```text
BLOCK  secret.github_token
Found a GitHub token in an agent-visible diff. Evidence is redacted before reporting.

REVIEW  mcp.broad_filesystem_access
MCP configuration exposes a broad filesystem root with write-capable access.

Verdicts:

• PASS: findings 없음
• REVIEW: 사람이 검토해야 할 비치명 finding
• BLOCK: critical secret/full-access finding 또는 높은 aggregate risk

호환성 경계

한국어 README는 제품 포지셔닝, 운영 설명, 팀 협업 맥락을 한국어 우선으로 제공합니다. 하지만 다음 machine-facing 계약은 한국어로 바꾸지 않습니다.

• CLI commands: agentguard scan-files, agentguard scan-diff, agentguard scan-mcp, agentguard doctor
• Rule IDs: secret.github_token, mcp.broad_filesystem_access
• Markdown terminal reports: 기본값은 한국어, --lang en으로 영어 Markdown 출력 가능
• SARIF/API/machine fields: GitHub code scanning, JSON, SARIF 2.1.0, CI 파서가 읽는 필드 이름
• Package metadata and command flags: npm, shell, GitHub Actions에서 쓰는 영어 식별자

이 경계 덕분에 한국 팀은 문서를 한국어로 읽고 운영할 수 있고, CI/CD, SARIF, API, 보안 리포팅은 기존 글로벌 도구와 그대로 연동됩니다.

문서

• [GitHub Actions / SARIF setup](docs/github-action.md)
• [Team rollout baseline guide](docs/team-rollout-baseline-guide.md)
• [Policy files](docs/policy.md)
• [Rule surfaces](docs/rules.md)
• [Examples](docs/examples.md)
• [AX prelim submission pack](docs/ax-prelim-submission-pack.md)
• [AX prelim judge Q&A](docs/ax-prelim-judge-qa.md)
• [AX rule compliance checklist](docs/ax-rule-compliance-checklist.md)
• [AX demo scenario matrix](docs/ax-demo-scenario-matrix.md)
• [AX demo failure mode register](docs/ax-demo-failure-mode-register.md)
• [AX live demo runbook](docs/ax-live-demo-runbook.md)
• [AX demo operator checklist](docs/ax-demo-operator-checklist.md)
• [AX 30-second demo command card](docs/ax-30-second-demo-card.md)
• [AX first-60-seconds evidence priority card](docs/ax-first-60-seconds-evidence-priority.md)
• [AX cross-shell demo command card](docs/ax-cross-shell-demo-command-card.md)
• [AX CLI benchmark quickstart card](docs/ax-cli-benchmark-quickstart-card.md)
• [AX demo-day command rehearsal](docs/ax-demo-day-command-rehearsal.md)
• [AX 90-second judge evidence tour](docs/ax-90-second-judge-evidence-tour.md)
• [AX AI judge evidence manifest](docs/ax-ai-judge-evidence-manifest.md)
• [AX before/after rollout demo](docs/ax-before-after-rollout-demo.md)
• [AX agent rollback drill](docs/ax-agent-rollback-drill.md)
• [AX adversarial judge checklist](docs/ax-adversarial-judge-checklist.md)
• [AX judge evidence index](docs/ax-judge-evidence-index.md)
• [AX judge evidence ladder](docs/ax-judge-evidence-ladder.md)
• [AX judge rubric crosswalk](docs/ax-judge-rubric-crosswalk.md)
• [AX rollout control map](docs/ax-rollout-control-map.md)
• [AX threat-control traceability card](docs/ax-threat-control-traceability.md)
• [AX rollout acceptance contract card](docs/ax-rollout-acceptance-contract-card.md)
• [AX boardroom go/no-go brief](docs/ax-boardroom-go-no-go-brief.md)
• [AX CI reviewer handoff](docs/ax-ci-reviewer-handoff.md)
• [AX CI evidence handoff card](docs/ax-ci-evidence-handoff-card.md)
• [AX SARIF reviewer loop card](docs/ax-sarif-reviewer-loop-card.md)
• [AX package provenance reviewer handoff card](docs/ax-package-provenance-handoff.md)
• [AX release attestation receipt](docs/ax-release-attestation-receipt.md)
• [AX PR gate first-run decision record](docs/ax-pr-gate-first-run-decision-record.md)
• [AX reference command routing card](docs/ax-reference-command-routing-card.md)
• [AX MCP consent/token handoff card](docs/ax-mcp-consent-token-handoff.md)
• [AX MCP third-party server trust boundary card](docs/ax-mcp-third-party-server-trust-boundary.md)
• [AX authorization callback state card](docs/ax-authorization-callback-state-card.md)
• [AX MCP authorization proof queue](docs/ax-mcp-authorization-proof-queue.md)
• [AX agent asset inventory card](docs/ax-agent-asset-inventory-card.md)
• [AX reviewer channel routing card](docs/ax-reviewer-channel-routing-card.md)
• [AX alert triage queue runbook](docs/ax-alert-triage-queue-runbook.md)
• [AX critical alert routing card](docs/ax-critical-alert-routing-card.md)
• [AX executive risk memo](docs/ax-executive-risk-memo.md)
• [AX real judge demo map](docs/ax-real-judge-demo-map.md)
• [AX judge handoff packet](docs/ax-judge-handoff-packet.md)
• [AX agent permission review packet](docs/ax-agent-permission-review-packet.md)
• [AX agent skill inventory evidence card](docs/ax-agent-skill-inventory-evidence-card.md)
• [AX agent runner sandbox boundary](docs/ax-agent-runner-sandbox-boundary.md)
• [AX data egress approval route](docs/ax-data-egress-approval-route.md)
• [AX env custody approval route](docs/ax-env-custody-approval-route.md)
• [AX approval owner escalation matrix](docs/ax-approval-owner-escalation-matrix.md)
• [AX security reviewer question bank](docs/ax-security-reviewer-question-bank.md)
• [AX workspace trust approval checklist](docs/ax-workspace-trust-approval-checklist.md)
• [AX prompt-injection evidence routing card](docs/ax-prompt-injection-evidence-routing-card.md)
• [AX submission readiness scorecard](docs/ax-submission-readiness-scorecard.md)
• [AX onsite triage card](docs/ax-onsite-triage-card.md)
• [AX onsite decision log](docs/ax-onsite-decision-log.md)
• [AX 6-hour onsite execution board](docs/ax-6-hour-onsite-execution-board.md)
• [AX onsite pivot guide](docs/ax-onsite-pivot-guide.md)
• [AX Rollout references](docs/ax-rollout-references.md)
• [AX reference refresh drill](docs/ax-reference-refresh-drill.md)
• [AX evidence freshness checklist](docs/ax-evidence-freshness-checklist.md)
• [AX evidence expiry revalidation card](docs/ax-evidence-expiry-revalidation-card.md)
• [AX evidence retention policy card](docs/ax-evidence-retention-policy.md)
• [AX policy exception decision tree](docs/ax-policy-exception-decision-tree.md)
• [AX false-positive dispute review card](docs/ax-false-positive-dispute-card.md)
• [AX competitive comparison](docs/ax-competitive-comparison.md)
• [AX public scanner ecosystem triage](docs/ax-public-scanner-ecosystem-triage.md)
• [AX public scanner gap checklist](docs/ax-public-scanner-gap-checklist.md)
• [AX public scanner freshness scorecard](docs/ax-public-scanner-freshness-scorecard.md)
• [AX public scanner signal refresh ledger](docs/ax-public-scanner-signal-refresh-ledger.md)
• [AX public reference fallback provenance card](docs/ax-public-reference-fallback-provenance.md)
• [AX public reference decision matrix](docs/ax-public-reference-decision-matrix.md)
• [AX public-reference source-status drill](docs/ax-public-reference-source-status-drill.md)
• [AX public reference validation card](docs/ax-public-reference-validation-card.md)
• [AX third-party agent scanner due diligence card](docs/ax-third-party-agent-scanner-due-diligence.md)
• [AX emergency stop runbook](docs/ax-emergency-stop-runbook.md)
• [AX guardrail tripwire evidence card](docs/ax-guardrail-tripwire-evidence-card.md)
• [AX guardrail review checkpoints](docs/ax-guardrail-review-checkpoints.md)
• [AX agent hook event approval route](docs/ax-agent-hook-event-approval-route.md)
• [AX agent tool onboarding readiness](docs/ax-agent-tool-onboarding-readiness.md)
• [AX human approval gate checklist](docs/ax-human-approval-gate-checklist.md)
• [AX agent rollout preflight checklist](docs/ax-agent-rollout-preflight-checklist.md)
• [AX control objective map](docs/ax-control-objective-map.md)
• [AX control-plane CI gate card](docs/ax-control-plane-ci-gate-card.md)
• [AX public-reference evidence triage card](docs/ax-public-reference-evidence-triage.md)
• [AX agentic tool-use approval queue](docs/ax-agentic-tool-use-approval-queue.md)
• [AX evidence acceptance receipt](docs/ax-evidence-acceptance-receipt.md)
• [AX review artifact acceptance checklist](docs/ax-review-artifact-acceptance-checklist.md)
• [AX fresh-clone verifier card](docs/ax-fresh-clone-verifier-card.md)
• [AX public signal-to-proof queue](docs/ax-public-signal-to-proof-queue.md)
• [AX agent action custody route](docs/ax-agent-action-custody-route.md)
• [AX official public-signal freshness](docs/ax-official-public-signal-freshness.md)
• [AX competitor objection answer card](docs/ax-competitor-objection-answer-card.md)
• [AX company problem intake kit](docs/ax-company-problem-intake-kit.md)
• [AX evidence receipt checklist](docs/ax-evidence-receipt-checklist.md)
• [AX verdict vocabulary glossary](docs/ax-verdict-vocabulary-glossary.md)
• [AX source-of-record audit card](docs/ax-source-of-record-audit-card.md)
• [AX fork PR artifact fallback card](docs/ax-fork-pr-artifact-fallback-card.md)
• [AX evidence custody chain](docs/ax-evidence-custody-chain.md)
• [AX evidence tamper/replay check](docs/ax-evidence-tamper-replay-check.md)
• [AX public evidence redaction boundary](docs/ax-public-evidence-redaction-boundary.md)
• [AX evidence-to-approver channel map](docs/ax-evidence-to-approver-channel-map.md)
• [AX evidence command failure triage card](docs/ax-evidence-command-failure-triage.md)
• [AX evidence freshness SLA card](docs/ax-evidence-freshness-sla-card.md)
• [AX evidence pack exit criteria card](docs/ax-evidence-pack-exit-criteria.md)
• [AX judging lens trace card](docs/ax-judging-lens-trace-card.md)
• [AX evidence bundle manifest](docs/ax-evidence-bundle-manifest.md)
• [AX smoke evidence manifest handoff card](docs/ax-smoke-evidence-manifest-handoff-card.md)
• [AX demo evidence freeze checklist](docs/ax-demo-evidence-freeze-checklist.md)
• [AX evidence freeze sign-off ledger](docs/ax-evidence-freeze-signoff-ledger.md)
• [AX pilot responsibility card](docs/ax-pilot-responsibility-card.md)
• [AX incident response evidence card](docs/ax-incident-response-evidence-card.md)
• [AX finding lifecycle approval card](docs/ax-finding-lifecycle-approval-card.md)
• [AX agent feedback-loop evidence card](docs/ax-agent-feedback-loop-evidence-card.md)
• [AX timeboxed escalation drill](docs/ax-timeboxed-escalation-drill.md)
• [AX reviewer non-response fallback card](docs/ax-reviewer-nonresponse-fallback-card.md)
• [AX CLI trust onboarding card](docs/ax-cli-trust-onboarding-card.md)
• [AX agent change-control evidence card](docs/ax-agent-change-control-evidence-card.md)
• [AX assumption ledger](docs/ax-assumption-ledger.md)
• [AX public-reference delta watch](docs/ax-public-reference-delta-watch.md)
• [AX final company-problem worksheet](docs/ax-final-problem-worksheet.md)
• [AX final submission smoke checklist](docs/ax-final-submission-smoke-checklist.md)
• [Roadmap](docs/roadmap.md)
• [Development harness](docs/harness-workflow.md)

예제 파일

• [examples/risky-mcp.json](examples/risky-mcp.json) — 위험한 MCP filesystem config
• [examples/risky-pr.diff](examples/risky-pr.diff) — fake secret-like material이 포함된 PR diff
• [examples/agent-transcript.log](examples/agent-transcript.log) — 위험한 shell behavior가 포함된 agent transcript
• [examples/expected-report.md](examples/expected-report.md) — sample markdown report
• [examples/agentguard.sarif](examples/agentguard.sarif) — sample SARIF payload

팀 PR gate workflow

팀 repo에 바로 붙일 때는 [GitHub Actions / SARIF setup](docs/github-action.md)의 AgentGuard PR gate 예제를 권장합니다. 이 reusable action은 PR diff를 스캔하고 Markdown/JSON/SARIF artifact를 만들며, 기본값 fail-on: block으로 advisory finding을 제외한 위험 점수 기준 BLOCK 판정만 merge gate에서 막습니다.

- uses: Sungho-pk42ac/agentguard@main
  with:
    base-sha: ${{ github.event.pull_request.base.sha }}
    head-sha: ${{ github.event.pull_request.head.sha }}
    report-path: agent-risk-report.md
    json-path: agent-risk-findings.json
    sarif-path: agentguard.sarif
    fail-on: block

GitHub code scanning workflow

아래 workflow를 .github/workflows/agentguard-sarif.yml로 복사하면 pull request diff를 스캔하고 agentguard.sarif를 생성한 뒤 GitHub code scanning에 업로드합니다. scan-diff --sarif --out agentguard.sarif 명령은 현재 구현된 CLI flags와 일치합니다.

name: AgentGuard code scanning
on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  security-events: write

jobs:
  agentguard-sarif:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run build

      - name: Emit AgentGuard SARIF
        run: |
          git diff --unified=0 ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }} \
            | node dist/index.js scan-diff --sarif --out agentguard.sarif || true

      - name: Upload AgentGuard SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: agentguard.sarif
          category: agentguard-pr-diff

GitHub PR comment workflow

아래 workflow를 .github/workflows/agentguard-pr.yml로 복사하면 pull request diff를 스캔하고 markdown report를 artifact로 보존하며, 같은 report를 PR comment로 게시합니다. Critical findings는 check를 실패시키고, review-level findings는 사람이 검토할 수 있도록 check를 green으로 유지합니다.

name: AgentGuard PR scan
on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  agentguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/chec

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Sungho-pk42ac](https://github.com/Sungho-pk42ac)
- **Source:** [Sungho-pk42ac/agentguard](https://github.com/Sungho-pk42ac/agentguard)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.