Özel politikalar

Özel politikalar, izlemelerizdeki veya denetimlerinizden bir hata kalıbını bir aracı çalışırken çalışan bir karara dönüştürür. Bir politika bir işleme izin verebilir, aracıya rehberlik sağlayabilir veya başka bir olay meydana gelmeden önce işlemi reddedebilir. Davranış araçlarınız, yollarınız, komutlarınız, ortamlarınız veya işletme kurallarınıza bağlı olduğunda özel bir politika kullanın. Mevcut bir kontrolü yeniden oluşturmamak için önce Failproof AI politika paketini kontrol edin.

Özel politika yazın

Dashboard
CLI

Admin → policy editor bölümüne gidin, New policy seçeneğini belirleyin ve önlemek istediğiniz hatayı açıklayın.
Politika kaynak kodunu ekleyin, ardından editörde beklenen eşleşmeleri ve güvenli eşleşmeyenleri test edin. Her doğrulama hatasını çözün.
taslağı kaydedin ve Publish version seçeneğini belirterek değişmez bir sürüm oluşturun.
Admin → enforcement bölümüne gidin, sürümü test makinasına observe modunda dağıtın ve uygulamadan önce kararlarını Observe → policy bölümünde doğrulayı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 ile doğrulayın ve yükleyin.
Eşleşen bir işlemi ve bir güvenli işlemi tetikleyin. failproofai policies komutunu çalıştırın, ardından Observe → policy bölümünde atfedilen kararları inceleyin.

Dar bir kuralla başlayın

Bu politika, komut üretimi hedeflediğinde yalnızca yıkıcı Kubernetes komutlarını engeller. Bu tam 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. Gözlemlenebilen işlemi eşleştirin—aracının hangi niyeti olduğunu değil—ve kural uygulanmadığı anda allow() döndürün.

Bir karar seçin

Yardımcı	Sonuç	Şu durumlarda kullanın
`allow(reason?)`	İşlem devam eder.	Politika uygulanmaz veya işlem güvenlidir.
`instruct(reason)`	İşlem, koşulu destekleyen yerlerde rehberlik ile devam eder.	Aracıyı bir değişkeni uygulamadan daha iyi bir yaklaşıma yönlendirmek istediğinizde.
`deny(reason)`	Olay ve koşul engellemeyi desteklediğinde işlem engellenir.	İşlem devam etmemelidir.

Aracının kurtarması gereken nedeni yazın. Neyin tespit edildiğini ve bunun yerine ne yapması gerektiğini açıklayın.

Güvenlik sınırı için instruct() kullanmayın. Rehberlik sunumu, aracı koşuluna göre değişir. İşlem engellenmelidir 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 sabit tanımlayıcı. Adları dosyalar arasında benzersiz tutun.
`description`	Hayır	Politika listelerinde ve kararlarda gösterilen okunabilir amaç.
`match.events`	Hayır	Politikayı çağıran olay türleri. `match` atlanırsa her kullanılabilir olay için çağrılır.
`fn`	Evet	`allow`, `instruct` veya `deny` sonucu döndüren eşzamanlı veya eşzamansız işlev.

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

Politika bağlamı

Her politika bir PolicyContext alır.

Alan	Tür	İçeriği
`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`	Mevcut araç çağrısı için kanonik giriş.
`payload`	`Record<string, unknown>`	Tam normalleştirilmiş olay yükü.
`session`	`SessionMetadata \| undefined`	Mevcut olduğunda oturum ID’si, çalışma dizini, transkript yolu, izin modu ve 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 ele alın. Aracı sürümleri ve olay türleri aynı alanları sağlamaz.

Ortak araç girdileri

Failproof AI, desteklenen koşullar arasında ortak araçları normalleştirir, böylece bir politika genellikle bir giriş şeklini 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ığından koruyucu zorlama kullanın:

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

Etkinliği seçin

Olay	Ne zaman çalışır	Tipik kullanım
`PreToolUse`	Bir araç yürütülmeden önce.	Komutları, yazıları, okumaları ve dış işlemleri engelle veya yönlendir.
`PostToolUse`	Bir araç döndükten sonra.	Sonuçları aracıya ulaşmadan önce incele. Bir reddetme tüm sonucu engeller; seçilen alanları redakte etmez.
`PermissionRequest`	Aracı izin istediğinde.	Kuruluşa özgü izin kurallarını uygula.
`UserPromptSubmit`	Gönderilen bir istem devam etmeden önce.	Yasak talimatları reddet veya iş akışı rehberliği ekle.
`Stop`	Aracı bitirmeye çalıştığında.	Yerel doğrulama adımı gibi ulaşılabilir bir tamamlama koşulu iste.
`SubagentStop`	Bir alt aracı bitirmeye çalıştığında.	Devredilen çalışmayı ebeveyne dönmeden önce kontrol et.
`SessionStart` / `SessionEnd`	Oturum sınırlarında.	Oturum düzeyi durumunu kaydet veya kontrol et.

Olay kullanılabilirliği ve engelleme davranışı aracı koşuluna bağlıdır. Karma bir filo arasında bir olaya güvenmeden önce Aracı koşulları bölümüne 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.

Ortak politika kalıplarını yazın

Korunan yollara yazmaları 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.");
  },
});

Bloke edilmeden rehberlik ver

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ı kontrol et

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 Stop olayı aracının yeniden denemesini sağlayabilir. Yalnızca aracının mevcut ortamda yerine getirebileceği bir koşul üzerinde engelle ve her alt işlem veya ağ çağrısını sınırla.

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öreli içeri aktarmalar desteklenir.
Proje politikaları kaydedilebilir, böylece aynı kurallar depo takip eder.

Açık dosyalar

Doğrulama veya yapılandırmanın giriş dosyasını doğrudan adlandırması gerektiğinde 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 yoldan da keşfedilen bir dosya bir kez yüklenir.

Doğrula ve test et

Doğrulama, modülü üretim yükleyicisinden geçirir 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öz dizimi hatalarını, çözülmemiş içeri aktarmaları, üst düzey istisnaları ve modül yükleme zaman aşımlarını yakalar. Bu, eşleşme mantığının doğru olduğunu kanıtlamaz. En az bu durumları test edin:

Eşleşmesi gereken ve amaçlanan politika nedenini üretmesi gereken bir işlem.
Güvenli olması gereken, yakındaki ancak güvenli bir işlem allow() döndürmeli.
Eksik veya hatalı araç alanları.
Alternatif komut söz dizimi, yollar, tırnak işaretleri, büyük/küçük harf ve boşluk.
Kullanılamayan bir alt işlem veya ağ bağımlılığı.

Sonucu Observe → policy bölümünde özel politikaya atfet. Farklı bir yerleşik politika kararı aldıysa 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.
Politika olayı reddetmediğinde birden fazla instruct sonucu birleştirilebilir.
Bir politika işlevinin 10 saniyelik yürütme süresi limiti vardır.
Atılan bir istisna veya zaman aşımı kaydedilir ve allow() olarak değerlendirilir.
Yüklemeyi başarısız olan bir kural dosyası atlanır; diğer özel dosyalar ve yerleşik politikalar devam eder.
Üst düzey modül yüklemenin de 10 saniyelik süresi limiti vardır.
Bulut observe modu politikayı çalıştırır ancak uygulamadan bir non-allow kararını kaydeder.

Politika modüllerini belirlenimci ve hızlı tutun. Üst düzey ağ çağrılarından veya sunucu başlatmadan kaçının. fn içinde çalışmayı sınırla, bağımlılık başarısızlıklarını yakala ve bu başarısızlığın işleme izin vermesi mi yoksa reddetmesi mi gerektiğine bilinçli olarak karar ver.

API dışa aktarmaları

Dışa aktarma	Amaç
`customPolicies.add(policy)`	Modül yüklendiğinde özel bir politika kaydet.
`allow(reason?)`	İşleme izin ver.
`instruct(reason)`	İşleme izin ver ve desteklenen yerlerde rehberlik sağla.
`deny(reason)`	Desteklenen yerlerde işlemi engelle.
`getCustomHooks()`	Modül kaydında şu anda kayıtlı olan politikaları döndür.
`clearCustomHooks()`	Bu kayıt defteri temizle, öncelikle testler ve yükleyiciler için.

TypeScript, PolicyContext, PolicyResult, CustomHook, PolicyDecision ve PolicyFunction dışa aktarır.