Przejdź do głównej treści
Nazwanie narzędzia i odmowa go to działanie tępe: zabija narzędzie dla każdego wywołania. Przez większość czasu narzędzie jest w porządku, a problemem jest jeden kształt wywołania — shell.exec jest w porządku, dopóki polecenie nie jest rm -rf, db.query jest w porządku, dopóki nie trafi w prod. To rozróżnienie wyraża klauzula argumentu: predykat argumentu narzędzia w jsonpath, który dopasowuje na wartościach, które agent przekazuje, więc werdykt odpala tylko na niebezpiecznym wywołaniu i zostawia resztę w spokoju. Ta strona to książka kucharska — garstka przepisów args_match_json do skopiowania na przypadki, które pojawiają się najczęściej. Dla pełnej gramatyki klauzul, tabeli operatorów i semantyki fail-closed zobacz Waliduj argumenty i referencję Schemat reguły.

​
1. Jak działa klauzula argumentu narzędzia w jsonpath

args_match_json reguły to string zakodowany w JSON niosący zestaw klauzul, wszystkie połączone AND. Zdekodowana wartość to obiekt, {"clauses": [ … ]}, gdzie każda klauzula to trójka { path, op, value }:
  • path — mały podzbiór JSONPath nad obiektem argumentów narzędzia: $.command, $.foo.bar, $.items[0] lub $ dla całego obiektu. Bez symboli wieloznacznych, filtrów, wycinków ani rekurencyjnego zstępowania.
  • op — jeden z zamkniętego zestawu: eq, contains, regex, in, cidr_match, gt, lt.
  • value — literał do porównania (string, liczba, bool lub — dla in — tablica JSON).
Klauzula jest połączona AND z tool_name_glob reguły: reguła odpala tylko, gdy nazwa narzędzia dopasuje i każda klauzula zachodzi. Pomiń args_match_json całkowicie (lub zostaw je puste "{}"), a reguła dopasowuje na samym globie.
Klauzule fail closed — reguła, nie żądanie. Jeśli ścieżka się nie rozwiązuje, argumenty są zniekształcone albo wartość jest złego typu, klauzula ewaluuje się do false, a reguła po prostu nie odpala — wywołanie spada do następnej reguły lub werdyktu domyślnego. Zepsuta klauzula nigdy nie auto-odmawia. Napisz swój twardy backstop jako zwykłe deny po globie, nie jako klauzulę, na której polegasz, by zawiodła w określony sposób.

​
2. Przepis: zablokuj jedno destrukcyjne polecenie

Kanoniczny przypadek. Zezwól na shell.exec ogólnie, odmów go tylko, gdy polecenie wygląda destrukcyjnie. Klauzula regex na $.command to robi: 
{
  "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=\"}]}"
}
Regexy to Go RE2 — czas liniowy, bez wstecznych odwołań, bez katastroficznego backtrackingu — więc bezpiecznie je uruchamiać przy każdym wywołaniu narzędzia. Niestringowy $.command (lub brakujący) nigdy nie dopasowuje, więc zniekształcone wywołanie spada zamiast zostać błędnie zablokowanym.
Preferuj contains nad regex, gdy dopasowujesz stały podłańcuch — jest prostszy do odczytania i nie może go potknąć nieescapowany metaznak. Sięgaj po regex tylko, gdy naprawdę potrzebujesz alternacji lub kotwic.

​
3. Przepis: odmów narzędzia wobec nazwanego środowiska

Pozwól db.query działać, ale tylko wobec bezpiecznych połączeń — odmów go, gdy cel to prod lub replica. Operator in dopasowuje rozwiązaną wartość wobec dowolnego elementu tablicy 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\"]}]}"
}
Wartość in musi być tablicą JSON — nie-tablica jest odrzucana przy zapisie reguły. Elementy porównują się z równością skalarną, więc liczby i stringi każde dopasowują własny typ.

​
4. Przepis: odmów celu z prywatnym IP lub metadanymi

Gdy narzędzie przyjmuje docelowe IP jako argument, cidr_match testuje, czy wpada w CIDR — kształt SSRF „agenta pobierającego 10.x lub adres metadanych chmury”: 
{
  "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\"}]}"
}
Wartość argumentu musi parsować się jako literał IP, który siedzi wewnątrz CIDR; nazwa hosta lub nie-IP string nigdy nie dopasowuje.
cidr_match inspekcjonuje tylko wartość, która jest już w argumentach narzędzia. Do zarządzania celem, do którego narzędzie faktycznie sięga na warstwie sieciowej — listy dozwolonych i odmów host/CIDR — użyj zamiast tego dedykowanej reguły egress na powierzchni egress. Te dwie są komplementarne: inspekcja argumentów na wejściu, kontrola egress na wyjściu.

​
5. Przepis: ogranicz argument numeryczny

gt i lt porównują liczby. Użyj ich, by odmówić absurdalnego rozmiaru partii, zbyt dużego limitu lub dowolnego rozbieganego licznika — tutaj odmów zbiorczego usunięcia, które celuje w więcej niż 100 wierszy: 
{
  "label": "block large bulk deletes",
  "tool_name_glob": "*.bulk_delete",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.count\",\"op\":\"gt\",\"value\":100}]}"
}
Obie strony muszą być liczbami — wyglądający numerycznie string jak "500" to niezgodność typu i nie dopasowuje, więc reguła nie odpali na argumencie typu stringowego. Trzymaj argument numerycznym lub normalizuj go, zanim narzędzie go zobaczy.

​
6. Przepis: łącz klauzule (AND)

Wszystkie klauzule w jednej regule łączą się AND, więc możesz zacieśnić werdykt do bardzo konkretnego wywołania — na przykład odmów shell.exec tylko, gdy to destrukcyjne polecenie i jest wymierzone w host 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\"]}]}"
}
Potrzebujesz OR zamiast tego? Nie ma OR wewnątrz pojedynczego args_match_json — napisz dwie reguły (lub dwa globy) na różnych priorytetach. Silnik przechodzi reguły w kolejności priorytetów i wygrywa pierwsze dopasowanie, więc umieść wąskie reguły pierwsze. Zobacz Priorytet reguł.

​
7. Wybierz werdykt dla dopasowanego kształtu

Klauzula decyduje, które wywołania dopasowują; verdict reguły decyduje, co się dzieje. deny to domyślny w książce kucharskiej, ale ta sama klauzula może nieść łagodniejszy werdykt:
Gdy dopasowany argument niesie sekret lub PII zamiast niebezpiecznej instrukcji, sanitize redaguje dopasowane podłańcuchy z argumentów narzędzia i przesyła oczyszczone wywołanie. Redaguje wyłącznie argumenty — nigdy treść, którą narzędzie zwraca. Zobacz Sanityzacja odpowiedzi.
Wstrzymaj dokładnie ryzykowny kształt do przeglądu zamiast blokować go wprost: recenzent zatwierdza lub odrzuca poza pasmem, a agent ponownie wysyła zatwierdzone wywołanie raz. Zobacz Zatwierdzenia.
Ustaw werdykt na audit, aby zarejestrować dopasowane wywołanie bez blokowania, gdy stroisz klauzulę. Połącz z trybem cienia, by zmierzyć deny wobec ruchu na żywo, zanim cokolwiek zmieni.

​
8. Przetestuj klauzulę, zanim na niej polegniesz

Zakładka Test w konsoli robi dry-run polityki wobec przykładowego wywołania narzędzia i zwraca werdykt, dopasowaną regułę i powód — nic nie jest dyspozytowane, nic persystowane. Wklej realistyczny obiekt argumentów i potwierdź, że klauzula odpala na wywołaniach, które masz na myśli, i tylko tych, ponieważ klauzula, która nie może rozwiązać wartości, po cichu nie odpala. Zobacz Testowanie reguł.
Klauzule są walidowane ściśle przy zapisie — nieznane operatory, złe ścieżki, nie-tablicowa wartość in, niekompilowalny regex i nieprawidłowe CIDR-y są wszystkie odrzucane, więc zniekształcona klauzula nie może być persystowana w pierwszej kolejności.

​
9. Kto może pisać klauzule argumentów

Wszystko to działa w konsoli pod twoją sesją (/api/workspace/firewall/*):
AkcjaRola
Odczyt polityk, presetów, wykrytych narzędziMember
Tworzenie / edycja / usuwanie regułDeveloper+
Piaskownica Test (dry-run polityki)Developer+
Odczyt zdarzeń i agregatów uruchomieńDeveloper+
Autorowanie lub zmiana klauzuli argumentu to zapis Developer+. Piaskownica Test jest też Developer+ — może podglądać wobec roboczej polityki, a jej trace werdyktu odsłania nazwy polityk i etykiety reguł, więc siedzi po stronie zapisu, nie odczytu.

​
Powiązane

Waliduj argumenty

Przypadek użycia dopasowania argumentów w całości.

Blokuj narzędzia

Odmów całego narzędzia po nazwie — bez klauzuli.

Kontrola egress

Zarządzaj wychodzącymi celami host / IP / CIDR.

Schemat reguły

Każde pole, które reguła może nieść.

Priorytet reguł

Wygrywa pierwsze dopasowanie — porządkuj wąskie przed szerokimi.

Niebezpieczne wywołania narzędzi

Zagrożenie, któremu zaradzają te przepisy.