Policy sdk

title: “Özel politikalar” description: “Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın.” icon: “shield-plus”

Özel politikalar, izlemeleriniz veya denetimlerinizden bir hata modelini, bir aracı çalışırken çalışan bir karara dönüştürür. Bir politika bir işlemi izin verebilir, aracıya rehberlik sağlayabilir veya başka bir olaya neden olmadan işlemi reddedebilir. Davranış aracınızın araçlarına, yollarına, komutlarına, ortamlarına veya işletme kurallarına bağlı olduğunda özel bir politika kullanın. Mevcut bir kontrolü yeniden oluşturmamak için önce yerleşik politika kataloğunu kontrol edin.

Özel politika yazma

Dashboard
CLI

Admin → policy editor (politika editörü) sayfasına gidin, New policy (Yeni politika) seçin ve önlemek istediğiniz hatayı açıklayın.
Politika kaynağını ekleyin, ardından editörde beklenen eşleşmeleri ve güvenli eşleşmeleri test edin. Her doğrulama hatasını çözün.
taslağı kaydedin ve değişmez bir sürüm oluşturmak için Publish version (Sürümü yayımla) seçeneğini tıklayın.
Admin → enforcement (uygulamaya zorlama) sayfasına gidin, sürümü test makinasına observe (gözlemle) modunda dağıtın ve Observe → policy (Gözlemle → politika) altında kararlarını doğrulamadan önce zorlayın.

.failproofai/policies/checkout-policies.ts dosyasını oluşturun. Dosya adı policies.js, policies.mjs veya policies.ts ile bitmelidir.
customPolicies.add() ile bir veya daha fazla politika kaydedin.
Dosyayı failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project komutuyla doğrulayın ve yükleyin.
Eşleşen bir işlem ve güvenli bir işlem tetikleyin. failproofai policies komutunu çalıştırın, ardından Observe → policy (Gözlemle → politika) altındaki atanmış kararları inceleyin.

Dar bir kuralla başlayın

Bu politika, yalnızca komut üretimi hedeflediğinde yıkıcı Kubernetes komutlarını engeller. O kesin hata modu dışındaki her şey allow() döndürür.

import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

İyi politikalar bir cümle ile açıklanacak kadar dar olmalıdır. Umarım aracının niyeti olan değil gözlemlenebilir işlemi eşleştirin ve kural geçerli olmayınca hemen allow() döndürün.

Bir karar seçin

Yardımcı	Sonuç	Şu durumlarda kullanın
`allow(reason?)`	İşlem devam eder.	Politika geçerli değildir veya işlem güvenlidir.
`instruct(reason)`	İşlem, koşul aracı tarafından destekleniyorsa rehberlikle devam eder.	Aracıyı değişmezliği uygulamadan daha iyi bir yaklaşıma yönlendirmek istiyorsanız.
`deny(reason)`	Olay ve koşul engellemeyi destekliyorsa işlem engellenir.	İşlem ilerlememeli.

Kurtarması gereken aracı için sebebi yazın. Ne tespit edildiğini ve bunun yerine ne yapması gerektiğini açıklayın.

Bir güvenlik sınırı için instruct() kullanmayın. Rehberlik sunumu, aracı koşuluna göre değişir. İşlem önlenmelidir. deny() kullanın.

Politika nesnesi

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

Alan	Gerekli	Açıklama
`name`	Evet	Politika için kararlı tanımlayıcı. Dosyalar arasında adları benzersiz tutun.
`description`	Hayır	Politika listelerinde ve kararlarda gösterilen insan tarafından okunabilir amaç.
`match.events`	Hayır	Politikayı çağıran olay türleri. `match` atlarsanız, her kullanılabilir olay için çağrılır.
`fn`	Evet	`allow`, `instruct` veya `deny` sonucu döndüren eşzamanlı veya asenkron işlev.

fn içinde araçları filtreleyin. match.toolNames, genel özel politika türünün bir parçası değildir.

Politika bağlamı

Her politika bir PolicyContext alır.

Alan	Tür	İçerdiği şey
`eventType`	`HookEventType`	Şu anda değerlendirilen normalleştirilmiş olay.
`toolName`	`string \| undefined`	`Bash`, `Read`, `Write` veya `Edit` gibi kanonik araç adı.
`toolInput`	`Record<string, unknown> \| undefined`	Geçerli araç çağrısı için kanonik giriş.
`payload`	`Record<string, unknown>`	Tamamlanmış normalleştirilmiş olay yükü.
`session`	`SessionMetadata \| undefined`	Oturum kimliği, çalışma dizini, transkript yolu, izin modu ve mevcut olduğunda koşul meta verileri.
`cli`	`string \| undefined`	`claude`, `codex` veya `cursor` gibi kaynak aracı koşulu.
`params`	`Record<string, unknown>`	Yerleşik politika parametreleri. Özel politikalar şu anda boş bir nesne alır.

Her isteğe bağlı değeri gerçekten isteğe bağlı olarak değerlendirin. Aracı sürümleri ve olay türleri aynı alanları sağlamaz.

Yaygın araç girdileri

Failproof AI, desteklenen koşullar arasında yaygın araçları normalleştirir, böylece bir politika genellikle bir giriş şekli kullanabilir.

Araç	Ortak alanlar
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Araç giriş değerleri unknown olarak yazıldığı için savunmacı zorlama kullanın:

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Olayı seçin

Olay	Ne zaman çalıştırılır	Tipik kullanım
`PreToolUse`	Bir araç çalıştırılmadan önce.	Komutları, yazıları, okumaları ve dış işlemleri engelleyin veya rehberlik sağlayın.
`PostToolUse`	Bir araç sonucu döndürdükten sonra.	Sonuçları aracıya ulaşmadan önce inceleyin. Bir reddetme tüm sonucu engeller; seçilen alanları redakte etmez.
`PermissionRequest`	Aracı izin talep ettiğinde.	Kuruluşa özgü izin kuralları uygulayın.
`UserPromptSubmit`	Gönderilen bir istem devam etmeden önce.	Yasaklanmış talimatları reddedin veya iş akışı rehberliği ekleyin.
`Stop`	Aracı bitirmeyi denediğinde.	Yerel doğrulama adımı gibi erişilebilir bir tamamlanma koşulu gerektir.
`SubagentStop`	Bir alt aracı bitirmeyi denediğinde.	Yetkilendirilmiş işi ebeveyne dönmeden önce kontrol edin.
`SessionStart` / `SessionEnd`	Oturum sınırlarında.	Oturum düzeyindeki durumu kaydedin veya kontrol edin.

Olay kullanılabilirliği ve engelleme davranışı aracı koşuluna bağlıdır. Karışık bir filo arasında bir olaya güvenmeden önce Aracı koşulları makalesine bakın.

Tüm politika olay adları

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch ve Setup.

Yaygın politika modellerini yazın

Korumalı yollara yazıları engelle

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

Engel olmayan rehberlik sağla

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

Oturum tamamlanmasını kapıyı koru

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Reddedilen bir Stop olayı aracıyı yeniden denemeye yapabilir. Yalnızca aracının geçerli ortamda karşılayabileceği bir koşulda kapıyı koruyun ve her alt işlem veya ağ çağrısını sınırlayın.

Politika dosyalarını yükle

Kural dosyaları

Kural dosyaları otomatik olarak yüklenir:

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Proje ve kullanıcı politika dizinleri her ikisi de yüklenir.
Dosyalar her dizin içinde alfabetik olarak yüklenir.
Bir dosya policies.js, policies.mjs veya policies.ts ile bitmelidir.
Bir dosyada birden fazla customPolicies.add() çağrısı desteklenir.
Yerel modüllerden göreceli içe aktarmalar desteklenir.
Proje politikaları kaydedilebilir, böylece aynı kurallar depoyu takip eder.

Açık dosyalar

Doğrulama veya yapılandırma, giriş dosyasını doğrudan adlandırmalı olduğunda açık yolları kullanın:

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Açık dosyalar önce yüklenir, ardından proje kural dosyaları ve sonra kullanıcı kural dosyaları gelir. Her iki yol aracılığıyla keşfedilen bir dosya bir kez yüklenir.

Doğrula ve test et

Doğrulama, modülü üretim yükleyicisi aracılığıyla yürütür ve en az bir politika kaydettiğini onaylar.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

Doğrulama, eksik dosyaları, sözdizimi hatalarını, çözülmemiş içe aktarmaları, üst düzey istisnalar ve modül yükleme zaman aşımlarını yakalar. Match mantığınızın doğru olduğunu kanıtlamaz. En azından bu durumları test edin:

Eşleşmesi gereken ve amaçlanan politika sebebini üreten bir işlem.
Yakınlarda ancak güvenli olan allow() döndürmesi gereken bir işlem.
Eksik veya yanlış biçimlendirilmiş araç alanları.
Alternatif komut sözdizimi, yollar, alıntılama, harf durumu ve boşluk.
Kullanılamayan bir alt işlem veya ağ bağımlılığı.

Sonucu Observe → policy (Gözlemle → politika) altında özel politikanıza atayın. Farklı bir yerleşik politika kararı verirse, engellenen bir test yeterli değildir.

Çalışma zamanı davranışı

Yerleşik politikalar özel politikalardan önce değerlendirilir.
İlk deny daha fazla politika değerlendirmesini durdurur.
Hiçbir politika olayı reddetmediğinde birden fazla instruct sonucu birleştirilebilir.
Bir politika işlevinin 10 saniyelik bir yürütme süresi vardır.
Atılan bir istisna veya zaman aşımı günlüğe kaydedilir ve allow() olarak değerlendirilir.
Başarısız olarak yüklenmiş bir kural dosyası atlanır; diğer özel dosyalar ve yerleşik politikalar devam eder.
Üst düzey modül yükleme de 10 saniyelik bir süresi vardır.
Bulut gözlemle modu politikayı çalıştırır ancak onu uygulamadan izin olmayan bir kararı kaydeder.

Politika modüllerini belirli ve hızlı tutun. Üst düzey ağ çağrılarından veya sunucu başlatmadan kaçının. fn içindeki işi sınırlayın, bağımlılık başarısızlıklarını yakalayın ve bu başarısızlığın işleme izin verip vermeyeceğini veya reddetmesi gerekip gerekmediğini kasıtlı olarak seçin.

API dışa aktarmaları

Dışa aktarma	Amaç
`customPolicies.add(policy)`	Modül yüklenirken özel bir politika kaydedin.
`allow(reason?)`	İşleme izin verin.
`instruct(reason)`	İşleme izin verin ve destekleniyorsa rehberlik sağlayın.
`deny(reason)`	Destekleniyorsa işlemi engelleyin.
`getCustomHooks()`	Modül kayıt defterinde şu anda kayıtlı politikaları döndürün.
`clearCustomHooks()`	Bu kayıt defterini temizleyin, esas olarak testler ve yükleyiciler için.

TypeScript PolicyContext, PolicyResult, CustomHook, PolicyDecision ve PolicyFunction dışa aktarımını sağlar.

Özel politikaları dağıt

Bir sürümü yayımla, gözlemle modunda dağıt, kararları doğrula ve uygulamaya geçişi yap.

Connect your agents

Reference

title: “Özel politikalar” description: “Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın.” icon: “shield-plus”

Özel politika yazma

Dar bir kuralla başlayın

Bir karar seçin

Politika nesnesi

Politika bağlamı

Yaygın araç girdileri

Olayı seçin

Yaygın politika modellerini yazın

Korumalı yollara yazıları engelle

Engel olmayan rehberlik sağla

Oturum tamamlanmasını kapıyı koru

Politika dosyalarını yükle

Kural dosyaları

Açık dosyalar

Doğrula ve test et

Çalışma zamanı davranışı

API dışa aktarmaları

Özel politikaları dağıt

​title: “Özel politikalar” description: “Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın.” icon: “shield-plus”

​Özel politika yazma

​Dar bir kuralla başlayın

​Bir karar seçin

​Politika nesnesi

​Politika bağlamı

​Yaygın araç girdileri

​Olayı seçin

​Yaygın politika modellerini yazın

​Korumalı yollara yazıları engelle

​Engel olmayan rehberlik sağla

​Oturum tamamlanmasını kapıyı koru

​Politika dosyalarını yükle

​Kural dosyaları

​Açık dosyalar

​Doğrula ve test et

​Çalışma zamanı davranışı

​API dışa aktarmaları

Özel politikaları dağıt

title: “Özel politikalar” description: “Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın.” icon: “shield-plus”

Özel politika yazma

Dar bir kuralla başlayın

Bir karar seçin

Politika nesnesi

Politika bağlamı

Yaygın araç girdileri

Olayı seçin

Yaygın politika modellerini yazın

Korumalı yollara yazıları engelle

Engel olmayan rehberlik sağla

Oturum tamamlanmasını kapıyı koru

Politika dosyalarını yükle

Kural dosyaları

Açık dosyalar

Doğrula ve test et

Çalışma zamanı davranışı

API dışa aktarmaları