메인 콘텐츠로 건너뛰기
툴을 명명하고 거부하는 것은 무딥니다: 모든 호출에 대해 툴을 죽입니다. 대부분의 경우 툴은 괜찮고 한 형태의 호출이 문제입니다 — shell.exec은 명령이 rm -rf이기 전까지 괜찮고, db.query은 prod에 부딪히기 전까지 괜찮습니다. 그 구별이 인자 절이 표현하는 것입니다: 에이전트가 전달하는 값에 매치하는 jsonpath 툴 인자 술어로, 판정이 위험한 호출에만 발동하고 나머지는 그대로 둡니다. 이 페이지는 쿡북입니다 — 가장 자주 나오는 경우를 위한 소수의 복사-붙여넣기 args_match_json 레시피. 전체 절 문법, 연산자 표, 그리고 페일 클로즈 의미는 인자 검증과 규칙 스키마 레퍼런스를 참조하세요.

​
1. jsonpath 툴 인자 절이 작동하는 방식

규칙의 args_match_json은 JSON으로 인코딩된 문자열로, 모두 함께 AND된 절 집합을 담습니다. 디코딩된 값은 객체 {"clauses": [ … ]}이며, 각 절은 { path, op, value } 3중항입니다:
  • path — 툴의 인자 객체에 대한 작은 JSONPath 부분집합: $.command, $.foo.bar, $.items[0], 또는 전체 객체를 위한 $. 와일드카드, 필터, 슬라이스, 또는 재귀 하강 없음.
  • op — 닫힌 집합 중 하나: eq, contains, regex, in, cidr_match, gt, lt.
  • value — 비교할 리터럴(문자열, 숫자, 불, 또는 — in의 경우 — JSON 배열).
절은 규칙의 tool_name_glob에 AND됩니다: 규칙은 툴 이름이 매치하고 그리고 모든 절이 성립할 때만 발동합니다. args_match_json을 완전히 생략하거나(또는 빈 "{}"로 두면) 규칙은 glob만으로 매치합니다.
절은 페일 클로즈됩니다 — 요청이 아니라 규칙이. path가 해석되지 않거나, 인자가 잘못 형성되었거나, 값이 잘못된 타입이면, 절은 false로 평가되고 규칙은 그저 발동하지 않습니다 — 호출은 다음 규칙이나 기본 판정으로 떨어집니다. 깨진 절은 결코 자동 거부하지 않습니다. 하드 백스톱은 특정 방식으로 실패하기를 기대는 절이 아니라 평범한 glob deny로 작성하세요.

​
2. 레시피: 하나의 파괴적 명령 차단

정전(canonical) 사례. shell.exec을 일반적으로 허용하되, 명령이 파괴적으로 보일 때만 거부합니다. $.command에 대한 regex 절이 그것을 합니다: 
{
  "label": "block destructive shell commands",
  "tool_name_glob": "*.exec",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|mkfs|dd if=\"}]}"
}
Regex는 Go RE2입니다 — 선형 시간, 역참조 없음, 파국적 백트래킹 없음 — 그래서 모든 툴 호출에서 실행하기에 안전합니다. 문자열이 아닌 $.command(또는 없는 것)는 결코 매치하지 않으므로, 잘못 형성된 호출은 잘못 차단되기보다 떨어집니다.
고정 부분 문자열을 매치할 때는 regex보다 contains를 선호하세요 — 읽기 더 간단하고 이스케이프되지 않은 메타문자에 걸리지 않습니다. 정말로 교대(alternation)나 앵커가 필요할 때만 regex를 사용하세요.

​
3. 레시피: 명명된 환경에 대해 툴 거부

db.query을 실행하게 하되, 안전한 연결에 대해서만 — 대상이 prod나 replica일 때 거부. in 연산자는 해석된 값을 JSON 배열의 어떤 요소에든 매치합니다: 
{
  "label": "no agent queries against prod",
  "tool_name_glob": "db.query",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.connection\",\"op\":\"in\",\"value\":[\"prod\",\"replica\"]}]}"
}
in 값은 JSON 배열이어야 합니다 — 배열이 아닌 것은 규칙을 저장할 때 거부됩니다. 요소는 스칼라 동등성으로 비교하므로, 숫자와 문자열은 각자 자신의 타입에 매치합니다.

​
4. 레시피: 사설 IP 또는 메타데이터 목적지 거부

툴이 대상 IP를 인자로 받을 때, cidr_match는 그것이 CIDR 안에 떨어지는지 테스트합니다 — “에이전트가 10.x나 클라우드 메타데이터 주소를 가져오는” SSRF 형태: 
{
  "label": "deny tool calls aimed at RFC-1918",
  "tool_name_glob": "*",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.target_ip\",\"op\":\"cidr_match\",\"value\":\"10.0.0.0/8\"}]}"
}
인자 값은 CIDR 안에 위치하는 IP 리터럴로 파싱되어야 합니다; 호스트명이나 IP가 아닌 문자열은 결코 매치하지 않습니다.
cidr_match는 이미 툴 인자에 있는 값만 검사합니다. 툴이 네트워크 계층에서 실제로 도달하는 목적지를 통제하려면 — 호스트/CIDR 허용 및 거부 목록 — 대신 egress 표면의 전용 egress 규칙을 사용하세요. 둘은 상호 보완적입니다: 들어오는 길의 인자 검사, 나가는 길의 egress 제어.

​
5. 레시피: 수치 인자에 상한 설정

gt와 lt는 숫자를 비교합니다. 그것들을 사용해 터무니없는 배치 크기, 과대한 limit, 또는 폭주하는 카운트를 거부하세요 — 여기서는, 100행 넘게 타깃하는 벌크 삭제를 거부: 
{
  "label": "block large bulk deletes",
  "tool_name_glob": "*.bulk_delete",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.count\",\"op\":\"gt\",\"value\":100}]}"
}
양측 모두 숫자여야 합니다 — "500" 같은 숫자처럼 보이는 문자열은 타입 불일치이고 매치하지 않으므로, 규칙은 문자열로 타입 지정된 인자에는 발동하지 않습니다. 인자를 숫자로 유지하거나, 툴이 보기 전에 정규화하세요.

​
6. 레시피: 절 결합하기(AND)

한 규칙의 모든 절은 함께 AND되므로, 판정을 매우 특정한 호출로 좁힐 수 있습니다 — 예를 들어, shell.exec을 파괴적 명령이고 그리고 prod 호스트를 향할 때만 거부: 
{
  "label": "destructive shell on a prod host",
  "tool_name_glob": "*.exec",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"},{\"path\":\"$.host\",\"op\":\"in\",\"value\":[\"db-prod-1\",\"db-prod-2\"]}]}"
}
대신 OR이 필요한가요? 단일 args_match_json 안에는 OR이 없습니다 — 서로 다른 우선순위에서 두 규칙(또는 두 glob)을 작성하세요. 엔진은 규칙을 우선순위 순으로 순회하고 첫 매치가 이기므로, 좁은 규칙을 먼저 두세요. 규칙 우선순위 참조.

​
7. 매치된 형태에 대한 판정 고르기

절은 어떤 호출이 매치하는지를 결정합니다; 규칙의 verdict는 무슨 일이 일어나는지를 결정합니다. deny가 쿡북 기본값이지만, 같은 절이 더 부드러운 판정을 담을 수 있습니다:
매치된 인자가 위험한 지시사항이 아니라 시크릿이나 PII를 담을 때, sanitize는 툴 인자에서 매치된 부분 문자열을 가리고 정화된 호출을 전달합니다. 인자만 가립니다 — 툴이 반환하는 콘텐츠는 결코 아닙니다. 응답 정화 참조.
위험한 형태를 통째로 차단하는 대신 정확히 그것을 검토를 위해 보류: 검토자가 대역 외에서 승인 또는 거부하고, 에이전트가 승인된 호출을 한 번 재제출합니다. Approvals 참조.
절을 튜닝하는 동안 차단하지 않고 매치된 호출을 기록하려면 판정을 audit로 설정합니다. shadow mode와 짝지어 deny가 무언가를 변경하기 전에 라이브 트래픽에 대해 측정하세요.

​
8. 의존하기 전에 절 테스트

콘솔 Test 탭은 샘플 툴 호출에 대해 정책을 dry-run하고 판정, 매치된 규칙, 이유를 반환합니다 — 아무것도 디스패치되지 않고, 아무것도 영속화되지 않습니다. 현실적인 인자 객체를 붙여넣고 절이 의도한 호출에 그리고 오직 그것에만 발동하는지 확인하세요. 값을 해석할 수 없는 절은 조용히 발동하지 않기 때문입니다. 규칙 테스트 참조.
절은 저장 시 엄격하게 검증됩니다 — 알 수 없는 연산자, 잘못된 path, 배열이 아닌 in 값, 컴파일할 수 없는 regex, 그리고 유효하지 않은 CIDR가 모두 거부되므로, 잘못 형성된 절은 애초에 영속화될 수 없습니다.

​
9. 누가 인자 절을 작성할 수 있는가

이 모든 것은 세션하에 콘솔에서(/api/workspace/firewall/*) 실행됩니다:
액션역할
정책, 프리셋, discovered tools 읽기Member
규칙 생성 / 편집 / 삭제Developer+
Test 샌드박스(정책 dry-run)Developer+
이벤트 및 실행 집계 읽기Developer+
인자 절을 작성하거나 변경하는 것은 Developer+ 쓰기입니다. Test 샌드박스도 **Developer+**입니다 — 초안 정책에 대해 미리 보기할 수 있고 그 판정 트레이스가 정책 이름과 규칙 레이블을 노출하므로, 읽기 측이 아니라 쓰기 측 라인에 위치합니다.

​
관련

인자 검증

인자 매칭 사용 사례 전체.

툴 차단

전체 툴을 이름으로 거부 — 절 불필요.

Egress 제어

아웃바운드 호스트 / IP / CIDR 목적지를 통제합니다.

규칙 스키마

규칙이 담을 수 있는 모든 필드.

규칙 우선순위

첫 매치 승리 — 좁은 것을 넓은 것 앞에 정렬.

위험한 툴 호출

이 레시피들이 다루는 위협.