내장 정책 - FailproofAI

failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의 내장 정책을 제공합니다. 각 정책은 특정 훅 이벤트 유형과 툴 이름에 따라 실행됩니다. 9개의 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 파라미터를 허용합니다. 4개의 워크플로우 정책은 Claude가 종료되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.

개요

정책은 카테고리별로 분류됩니다:

카테고리	정책	훅 유형
위험한 명령어	block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands	PreToolUse
시크릿 (새니타이저)	sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens	PostToolUse
환경	block-env-files, protect-env-vars	PreToolUse
파일 접근	block-read-outside-cwd, block-secrets-write	PreToolUse
Git	block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged	PreToolUse
데이터베이스	warn-destructive-sql, warn-schema-alteration	PreToolUse
경고	warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install	PreToolUse
워크플로우	require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop	Stop

block- — 에이전트 진행을 차단합니다.
warn- — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다.
sanitize- — 에이전트에게 전달되기 전에 툴 출력에서 민감한 데이터를 제거합니다.
require- — 조건이 충족될 때까지 Stop 이벤트를 차단합니다.

모든 정책은 policyParams에서 선택적 hint 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 내장, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 구성 → hint를 참조하세요.

위험한 명령어

에이전트가 되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하는 것을 방지합니다.

`block-sudo`

이벤트: PreToolUse (Bash)
기본 동작: sudo 키워드가 포함된 모든 명령어를 차단합니다. sudo 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령어 토큰을 기준으로 수행되어, 셸 연산자 인젝션을 통한 우회를 방지합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용되는 정확한 명령어 프리픽스. 각 항목은 파싱된 argv 토큰과 대조하여 매칭됩니다.

예시:

{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}

이 설정을 사용하면 sudo systemctl status nginx는 허용되지만, sudo rm /etc/hosts는 차단됩니다.

패턴은 원시 명령어 문자열이 아닌 파싱된 토큰과 대조하여 매칭됩니다. 이를 통해 셸 연산자 추가를 통한 우회를 방지합니다 (예: sudo systemctl status x; rm -rf /는 sudo systemctl status *와 매칭되지 않습니다).

`block-rm-rf`

이벤트: PreToolUse (Bash)
기본 동작: rm -rf, rm -fr 및 유사한 재귀 삭제 형태를 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPaths`	`string[]`	`[]`	재귀 삭제가 허용되는 경로 (예: `/tmp`).

예시:

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}

`block-curl-pipe-sh`

이벤트: PreToolUse (Bash)
기본 동작: curl <url> | bash, curl <url> | sh, wget <url> | bash 및 유사한 패턴을 차단합니다. 파라미터 없음.

`block-failproofai-commands`

이벤트: PreToolUse (Bash)
기본 동작: failproofai 자체를 제거하거나 비활성화하려는 명령어를 차단합니다 (예: npm uninstall failproofai, failproofai policies --uninstall). 파라미터 없음.

시크릿 (새니타이저)

에이전트가 자격 증명을 컨텍스트나 출력에 노출시키는 것을 방지합니다. 새니타이저 정책은 PostToolUse 이벤트에서 실행됩니다. Claude가 Bash 명령어를 실행하거나, 파일을 읽거나, 어떤 툴을 호출할 때, 이 정책들은 출력이 Claude에게 반환되기 전에 검사합니다. 시크릿 패턴이 감지되면, 정책은 출력이 다시 전달되는 것을 막는 deny 결정을 반환합니다.

`sanitize-jwt`

이벤트: PostToolUse (모든 툴)
기본 동작: JWT 토큰 (.으로 구분된 세 개의 base64url 세그먼트)을 마스킹합니다. 파라미터 없음.

`sanitize-api-keys`

이벤트: PostToolUse (모든 툴)
기본 동작: 일반적인 API 키 형식을 마스킹합니다: Anthropic (sk-ant-), OpenAI (sk-), GitHub PAT (ghp_), AWS 액세스 키 (AKIA), Stripe 키 (sk_live_, sk_test_), Google API 키 (AIza). 파라미터:

파라미터	타입	기본값	설명
`additionalPatterns`	`{ regex: string; label: string }[]`	`[]`	시크릿으로 처리할 추가 정규식 패턴.

예시:

{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}

`sanitize-connection-strings`

이벤트: PostToolUse (모든 툴)
기본 동작: 자격 증명이 포함된 데이터베이스 연결 문자열을 마스킹합니다 (예: postgresql://user:password@host/db). 파라미터 없음.

`sanitize-private-key-content`

이벤트: PostToolUse (모든 툴)
기본 동작: PEM 블록(-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY----- 등)을 마스킹합니다. 파라미터 없음.

`sanitize-bearer-tokens`

이벤트: PostToolUse (모든 툴)
기본 동작: 토큰이 20자 이상인 Authorization: Bearer <token> 헤더를 마스킹합니다. 파라미터 없음.

환경

에이전트가 민감한 환경 구성을 읽거나 노출시키는 것을 보호합니다.

`block-env-files`

이벤트: PreToolUse (Bash, Read)
기본 동작: cat .env, .env를 파일 경로로 사용하는 Read 툴 호출 등을 통한 .env 파일 읽기를 차단합니다. .envrc나 다른 환경 관련 파일은 차단하지 않으며, 정확히 .env라는 이름의 파일만 차단합니다. 파라미터 없음.

`protect-env-vars`

이벤트: PreToolUse (Bash)
기본 동작: 환경 변수를 출력하는 명령어를 차단합니다: printenv, env, echo $VAR. 파라미터 없음.

파일 접근

에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 합니다.

`block-read-outside-cwd`

이벤트: PreToolUse (Read, Bash)
기본 동작: 현재 작업 디렉토리(프로젝트 루트) 외부의 파일 읽기를 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPaths`	`string[]`	`[]`	cwd 외부에 있더라도 허용되는 절대 경로 프리픽스.

예시:

{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}

`block-secrets-write`

이벤트: PreToolUse (Write, Edit)
기본 동작: 개인 키 및 인증서에 일반적으로 사용되는 파일에 대한 쓰기를 차단합니다: id_rsa, id_ed25519, *.key, *.pem, *.p12, *.pfx. 파라미터:

파라미터	타입	기본값	설명
`additionalPatterns`	`string[]`	`[]`	차단할 추가 파일명 패턴 (글로브 스타일).

예시:

{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}

Git

실수로 인한 푸시, 강제 푸시, 되돌리기 어려운 브랜치 실수를 방지합니다.

`block-push-master`

이벤트: PreToolUse (Bash)
기본 동작: git push origin main과 git push origin master를 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`protectedBranches`	`string[]`	`["main", "master"]`	직접 푸시할 수 없는 브랜치 이름.

예시:

{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}

enabledPolicies에서 정책을 제거하지 않고 모든 브랜치로의 푸시를 허용하려면 (사실상 정책 비활성화), protectedBranches: []로 설정하세요.

`block-work-on-main`

이벤트: PreToolUse (Bash)
기본 동작: main 또는 master 브랜치를 직접 체크아웃하는 것을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`protectedBranches`	`string[]`	`["main", "master"]`	직접 체크아웃할 수 없는 브랜치 이름.

`block-force-push`

이벤트: PreToolUse (Bash)
기본 동작: git push --force와 git push -f를 차단합니다. 정책별 파라미터 없음. 크로스커팅 hint를 사용하여 대안을 제안할 수 있습니다:

{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}

`warn-git-amend`

이벤트: PreToolUse (Bash)
기본 동작: git commit --amend 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령어 자체를 차단하지는 않습니다. 파라미터 없음.

`warn-git-stash-drop`

이벤트: PreToolUse (Bash)
기본 동작: git stash drop 실행 전에 Claude에게 확인하도록 안내합니다. 명령어 자체를 차단하지는 않습니다. 파라미터 없음.

`warn-all-files-staged`

이벤트: PreToolUse (Bash)
기본 동작: git add -A 또는 git add . 실행 시 Claude에게 스테이징할 내용을 검토하도록 안내합니다. 명령어 자체를 차단하지는 않습니다. 파라미터 없음.

데이터베이스

데이터베이스에 실행되기 전에 파괴적인 SQL 작업을 감지합니다.

`warn-destructive-sql`

이벤트: PreToolUse (Bash)
기본 동작: DROP TABLE, DROP DATABASE, 또는 WHERE 절 없는 DELETE가 포함된 SQL 실행 전에 Claude에게 확인하도록 안내합니다. 파라미터 없음.

`warn-schema-alteration`

이벤트: PreToolUse (Bash)
기본 동작: ALTER TABLE 구문 실행 전에 Claude에게 확인하도록 안내합니다. 파라미터 없음.

경고

파괴적이지는 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.

`warn-large-file-write`

이벤트: PreToolUse (Write)
기본 동작: 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다. 파라미터:

파라미터	타입	기본값	설명
`thresholdKb`	`number`	`1024`	경고가 발생하는 파일 크기 임계값 (킬로바이트).

예시:

{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}

훅 핸들러는 페이로드에 대해 1 MB stdin 제한을 적용합니다. 소용량 콘텐츠로 이 정책을 테스트하려면 thresholdKb를 1024보다 훨씬 낮은 값으로 설정하세요.

`warn-package-publish`

이벤트: PreToolUse (Bash)
기본 동작: npm publish 실행 전에 Claude에게 확인하도록 안내합니다. 파라미터 없음.

`warn-background-process`

이벤트: PreToolUse (Bash)
기본 동작: nohup, &, disown, 또는 screen을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다. 파라미터 없음.

`warn-global-package-install`

이벤트: PreToolUse (Bash)
기본 동작: npm install -g, yarn global add, 또는 가상 환경 없이 pip install 실행 전에 Claude에게 확인하도록 안내합니다. 파라미터 없음.

AI 동작

에이전트가 멈추거나 예기치 않게 동작하는 경우를 감지합니다.

`warn-repeated-tool-calls`

이벤트: PreToolUse (모든 툴)
기본 동작: 동일한 툴이 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 이는 에이전트가 루프에 빠진 일반적인 신호입니다. 파라미터 없음.

워크플로우

세션 종료 시 체계적인 워크플로우를 강제합니다. 이 정책들은 Stop 이벤트에서 실행되며, 각 조건이 충족될 때까지 Claude의 종료를 차단합니다. 커밋 → 푸시 → PR → CI의 자연스러운 의존성 체인을 따릅니다. 정책이 deny를 반환하면, 체인의 이후 정책은 건너뜁니다 (deny 단락 평가). 모든 워크플로우 정책은 fail-open 방식입니다: 필요한 툴을 사용할 수 없는 경우 (예: gh가 설치되지 않음, git 원격 없음), 정책은 검사를 건너뛴 이유를 설명하는 안내 메시지와 함께 허용합니다.

`require-commit-before-stop`

이벤트: Stop
기본 동작: 커밋되지 않은 변경 사항(수정됨, 스테이징됨, 추적되지 않는 파일)이 있을 때 종료를 차단합니다. 작업 디렉토리가 깨끗할 때는 안내 메시지를 반환합니다. 파라미터 없음.

`require-push-before-stop`

이벤트: Stop
기본 동작: 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 종료를 차단합니다. 필요한 경우 추적 브랜치 생성을 위해 git push -u를 제안합니다. 원격이 구성되지 않은 경우 fail-open 처리됩니다. 파라미터:

파라미터	타입	기본값	설명
`remote`	`string`	`"origin"`	푸시할 원격 이름.

예시:

{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}

`require-pr-before-stop`

이벤트: Stop
기본 동작: 현재 브랜치에 대한 풀 리퀘스트가 없거나, 기존 PR이 닫혔거나 머지된 경우 종료를 차단합니다. gh pr create로 PR을 생성하도록 Claude에게 안내합니다. 파라미터 없음.

이 정책은 GitHub CLI (gh)가 설치되고 인증되어 있어야 합니다. 풀 리퀘스트에 대한 읽기 접근을 위해 repo 스코프를 가진 개인 액세스 토큰으로 gh auth login을 실행하세요. gh가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.

`require-ci-green-before-stop`

이벤트: Stop
기본 동작: 현재 브랜치에서 CI 검사가 실패 중이거나 아직 실행 중일 때 종료를 차단합니다. GitHub Actions 워크플로우 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. skipped 결론은 성공으로 처리합니다. 모든 검사가 통과하면 안내 메시지를 반환합니다. 파라미터 없음.

이 정책은 GitHub CLI (gh)가 설치되고 인증되어 있어야 합니다. Actions 워크플로우 실행 및 Checks API에 대한 읽기 접근을 위해 repo 스코프를 가진 개인 액세스 토큰으로 gh auth login을 실행하세요. gh가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.

개별 정책 비활성화

설정 파일의 enabledPolicies에서 특정 정책을 제거하거나, 대시보드의 Policies 탭에서 토글로 끄세요.

{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}

enabledPolicies에 나열되지 않은 정책은 policyParams 항목이 존재하더라도 실행되지 않습니다.

시작하기

핵심 개념

CLI

도구

고급

​개요

​위험한 명령어

​block-sudo

​block-rm-rf

​block-curl-pipe-sh

​block-failproofai-commands

​시크릿 (새니타이저)

​sanitize-jwt

​sanitize-api-keys

​sanitize-connection-strings

​sanitize-private-key-content

​sanitize-bearer-tokens

​환경

​block-env-files

​protect-env-vars

​파일 접근

​block-read-outside-cwd

​block-secrets-write

​Git

​block-push-master

​block-work-on-main

​block-force-push

​warn-git-amend

​warn-git-stash-drop

​warn-all-files-staged

​데이터베이스

​warn-destructive-sql

​warn-schema-alteration

​경고

​warn-large-file-write

​warn-package-publish

​warn-background-process

​warn-global-package-install

​AI 동작

​warn-repeated-tool-calls

​워크플로우

​require-commit-before-stop

​require-push-before-stop

​require-pr-before-stop

​require-ci-green-before-stop

​개별 정책 비활성화

개요

위험한 명령어

`block-sudo`

`block-rm-rf`

`block-curl-pipe-sh`

`block-failproofai-commands`

시크릿 (새니타이저)

`sanitize-jwt`

`sanitize-api-keys`

`sanitize-connection-strings`

`sanitize-private-key-content`

`sanitize-bearer-tokens`

환경

`block-env-files`

`protect-env-vars`

파일 접근

`block-read-outside-cwd`

`block-secrets-write`

Git

`block-push-master`

`block-work-on-main`

`block-force-push`

`warn-git-amend`

`warn-git-stash-drop`

`warn-all-files-staged`

데이터베이스

`warn-destructive-sql`

`warn-schema-alteration`

경고

`warn-large-file-write`

`warn-package-publish`

`warn-background-process`

`warn-global-package-install`

AI 동작

`warn-repeated-tool-calls`

워크플로우

`require-commit-before-stop`

`require-push-before-stop`

`require-pr-before-stop`

`require-ci-green-before-stop`

개별 정책 비활성화