OmniRoute/docs/i18n/phi/SECURITY.md

Security Policy (Filipino)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Pag-uulat ng mga Kahinaan

Kung makatuklas ka ng kahinaan sa seguridad ng OmniRoute, mangyaring iulat ito nang responsable:

1. HUWAG magbukas ng pampublikong GitHub issue
2. Gamitin ang GitHub Security Advisories
3. Isama ang: paglalarawan, mga hakbang sa muling paglikha, at potensyal na epekto

Takdang Panahon ng Pagtugon

Yugto	Target
Pagkilala sa Ulat	48 oras
Pagsusuri at Pagtatasa	5 araw ng negosyo
Paglabas ng Patch	14 na araw ng negosyo (kritikal)

Mga Sinusuportahang Bersyon

Bersyon	Katayuan ng Suporta
3.8.x	✅ Aktibo
3.7.x	✅ Seguridad
< 3.7.0	❌ Hindi suportado

---

Arkitektura ng Seguridad

Nagpapatupad ang OmniRoute ng maraming patong na modelo ng seguridad:

Kahilingan → CORS → Authz pipeline (uriin → mga patakaran → ipatupad)
           → Mga Guardrail (PII masker, prompt injection, vision bridge)
           → Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider

🔐 Pagpapatotoo at Awtorisasyon

Feature	Pagpapatupad
Pag-login sa Dashboard	Pagpapatotoong nakabatay sa password gamit ang mga JWT token (HttpOnly cookies)
API Key Auth	Mga key na nilagdaan ng HMAC na may CRC validation
OAuth 2.0 + PKCE	Gumagamit ng PKCE ang browser/device OAuth na partikular sa provider kung sinusuportahan; hiwalay na pinangangasiwaan ang import-only na mga kredensyal ng Devin.
Token Refresh	Awtomatikong pag-refresh ng OAuth token bago ito mag-expire
Mga Ligtas na Cookie	AUTH_COOKIE_SECURE=true para sa mga HTTPS environment
Authz Pipeline	Pag-uuri ng route (PUBLIC / CLIENT_API / MANAGEMENT) — tingnan ang docs/architecture/AUTHZ_GUIDE.md
Mga Antas ng Route Guard	3-tier na modelo para sa mga management route (LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT) — tingnan ang docs/security/ROUTE_GUARD_TIERS.md
Manage-Scope MCP	Ang remote na access sa /api/mcp/* ay nililimitahan ng mga API key na may saklaw na manage; nananatiling strict-loopback ang /api/cli-tools/runtime/*. Tingnan ang ROUTE_GUARD_TIERS
Mga Saklaw ng MCP	32 detalyadong saklaw (read:health, write:combos, execute:completions, atbp.) — tingnan ang docs/frameworks/MCP-SERVER.md

🛡️ Pag-encrypt ng Nakaimbak na Data

Ang lahat ng sensitibong data na nakaimbak sa SQLite ay ine-encrypt gamit ang AES-256-GCM na may scrypt key derivation:

• Mga API key, access token, refresh token, at ID token
• Format na may bersyon: enc:v1:<iv>:<ciphertext>:<authTag>
• Passthrough mode (plaintext) kapag hindi nakatakda ang STORAGE_ENCRYPTION_KEY

# Bumuo ng encryption key:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

🛡️ Framework ng mga Guardrail

Kasama sa OmniRoute ang isang hot-reloadable na guardrails registry (src/lib/guardrails/) na may 3 built-in na guardrail na inayos ayon sa priyoridad:

Guardrail	Priyoridad	Layunin
vision-bridge	5	Inuugnay ang mga non-vision model sa mga paglalarawang may kamalayan sa larawan; proteksyon laban sa SSRF para sa mga URL ng larawan
pii-masker	10	Pag-redact ng PII bago at pagkatapos ng call (mga email, telepono, CPF, CNPJ, credit card, SSN)
prompt-injection	20	Tinutukoy ang mga pattern ng override/role-hijack/jailbreak/leak

Nagrerehistro ang mga custom na guardrail sa pamamagitan ng registerGuardrail(new MyGuardrail()). Fail-open ang modelo (hindi kailanman hinaharang ng mga exception ang trapiko). Maaaring mag-opt out sa bawat kahilingan sa pamamagitan ng header na x-omniroute-disabled-guardrails. → Tingnan ang docs/security/GUARDRAILS.md.

🧠 Proteksyon Laban sa Prompt Injection

Best-effort na heuristic middleware na tumutukoy ng mga pattern ng prompt injection sa mga kahilingan sa LLM. Hindi ito isang kumpletong firewall laban sa prompt injection — maaari itong magbigay ng mga false positive (mga lehitimong persona/RPG prompt) at false negative (leetspeak, paglalagay ng espasyo, mga pattern na hindi Ingles).

Uri ng Pattern	Kalubhaan	Halimbawa
System Override	Mataas	"huwag pansinin ang lahat ng naunang tagubilin"
Role Hijack	Katamtaman	"ikaw na ngayon si DAN, magagawa mo ang kahit ano"
Delimiter Injection	Mataas	Mga naka-encode na separator upang sirain ang mga hangganan ng konteksto
DAN/Jailbreak	Katamtaman	Mga kilalang pattern ng jailbreak prompt
Instruction Leak	Mataas	"ipakita mo sa akin ang iyong system prompt"
Encoding Evasion	Katamtaman	base64/rot13/hex decode + mga keyword ng tagubilin

Tanging mga pagtukoy na may Mataas na kalubhaan ang hinaharang sa block mode. Ang mga family na may katamtamang kalubhaan ay itinatala ngunit hindi kailanman hinaharang ng sanitizeRequest.

I-configure sa pamamagitan ng dashboard (Mga Setting → Seguridad) o .env:

INPUT_SANITIZER_ENABLED=true
INPUT_SANITIZER_MODE=block    # warn | block (patakaran sa injection; hindi inaalis ng lumang "redact" ang teksto ng injection)
INPUT_SANITIZER_BLOCK_THRESHOLD=high  # high (default) | medium | low — ang mga kalubhaan na katumbas o mas mataas dito ay hinaharang sa block mode

🔒 Pag-redact ng PII

Awtomatikong pagtukoy at opsyonal na pag-redact ng impormasyong personal na makapagpapakilala:

Uri ng PII	Pattern	Kapalit
Email	user@domain.com	[EMAIL_REDACTED]
CPF (Brazil)	123.456.789-00	[CPF_REDACTED]
CNPJ (Brazil)	12.345.678/0001-00	[CNPJ_REDACTED]
Credit Card	4111-1111-1111-1111	[CC_REDACTED]
Telepono	+55 11 99999-9999	[PHONE_REDACTED]
SSN (US)	123-45-6789	[SSN_REDACTED]

PII_REDACTION_ENABLED=true   # humiling ng muling pagsulat ng PII; hiwalay sa INPUT_SANITIZER_MODE
PII_RESPONSE_SANITIZATION=true  # opsyonal: i-redact ang PII sa mga tugon ng provider na ibinabalik sa mga client

🌐 Seguridad ng Network

Tampok	Paglalarawan
CORS	Tahasang allowlist ng cross-origin (CORS_ALLOWED_ORIGINS; legacy na CORS_ORIGIN)
Pag-filter ng IP	Mga saklaw ng IP sa allowlist/blocklist sa dashboard
Paglilimita ng Rate	Mga limitasyon sa rate kada provider na may awtomatikong backoff
Anti-Thundering Herd	Pinipigilan ng mutex + pag-lock kada koneksyon ang sunod-sunod na mga 502
TLS Fingerprint	Panghuhuwad ng TLS fingerprint na tulad ng browser upang mabawasan ang pagtukoy sa bot
CLI Fingerprint	Pagkakasunod-sunod ng header/body kada provider upang tumugma sa mga native na CLI signature

🔌 Katatagan at Availability

Tampok	Paglalarawan
Circuit Breaker	3-state (Sarado → Bukas → Kalahating Bukas) kada provider, naka-persist sa SQLite
Idempotency ng Request	5 segundong dedup window para sa mga dobleng request
Exponential Backoff	Awtomatikong muling pagsubok na may papataas na pagkaantala
Health Dashboard	Real-time na pagsubaybay sa kalagayan ng provider

📋 Pagsunod

Tampok	Paglalarawan
Pagpapanatili ng Log	Awtomatikong paglilinis pagkalipas ng CALL_LOG_RETENTION_DAYS
No-Log Opt-out	Hindi pinapagana ng flag na noLog kada API key ang pag-log ng request
Audit Log	Sinusubaybayan ang mga administratibong pagkilos sa talahanayang audit_log
MCP Audit	Audit logging na gumagamit ng SQLite para sa lahat ng tawag sa MCP tool
Zod Validation	Lahat ng input sa API ay bina-validate gamit ang mga schema ng Zod v4 sa pag-load ng module

---

Mga Kinakailangang Environment Variable

Dapat maitakda ang lahat ng secret bago simulan ang server. Agad na mabibigo ang server kung nawawala o mahina ang mga ito.

# KINAKAILANGAN — hindi magsisimula ang server kung wala ang mga ito:
JWT_SECRET=$(openssl rand -base64 48)     # hindi bababa sa 32 character
API_KEY_SECRET=$(openssl rand -hex 32)    # hindi bababa sa 16 na character

# INIREREKOMENDA — nagbibigay-daan sa pag-encrypt habang nakaimbak:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

Aktibong tinatanggihan ng server ang mga kilalang mahinang value tulad ng changeme, secret, o password.

---

Seguridad ng Docker

• Gumamit ng non-root user sa production
• I-mount ang mga secret bilang read-only volume
• Huwag kailanman kopyahin ang mga .env file sa mga Docker image
• Gumamit ng .dockerignore upang ibukod ang mga sensitibong file
• Itakda ang AUTH_COOKIE_SECURE=true kapag nasa likod ng HTTPS

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --read-only \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  -e JWT_SECRET="$(openssl rand -base64 48)" \
  -e API_KEY_SECRET="$(openssl rand -hex 32)" \
  -e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  diegosouzapw/omniroute:latest

---

Mga Dependency

• Regular na patakbuhin ang npm audit (sinasaklaw ng npm run audit:deps ang main + electron)
• Panatilihing napapanahon ang mga dependency
• Gumagamit ang proyekto ng husky + lint-staged para sa mga pre-commit check (lint-staged + check-docs-sync + check:any-budget:t11)
• Pinapatakbo ng CI pipeline ang mga panuntunan sa seguridad ng ESLint sa bawat push (no-eval, no-implied-eval, no-new-func = error)
• Bine-validate ang mga provider constant sa pag-load ng module sa pamamagitan ng Zod (src/shared/validation/schemas.ts)
• Mga library na secure bilang default ang ginagamit: dompurify / isomorphic-dompurify (XSS), jose (JWT), better-sqlite3 (walang panganib ng SQLi dahil sa mga parameterized query), bcryptjs (pag-hash ng password)

Mahihigpit na Panuntunan sa Seguridad

Ipinapatupad ng tooling at mga reviewer ang mga panuntunang ito:

1. Huwag kailanman mag-commit ng mga secret — naka-gitignore ang .env; ang .env.example ang template (walang mga literal, mga komento lamang — tingnan ang PUBLIC_CREDS.md sa ibaba)
2. Huwag kailanman gumamit ng eval(), new Function(), o implied eval — ipinapatupad ito ng ESLint
3. Huwag kailanman lampasan ang mga Husky hook (--no-verify, --no-gpg-sign) nang walang tahasang pag-apruba ng operator
4. Huwag kailanman magsulat ng raw SQL sa mga route — palaging dumaan sa src/lib/db/ (parameterized)
5. Palaging i-validate ang mga input gamit ang Zod — src/shared/validation/schemas.ts
6. Palaging i-sanitize ang mga upstream header — denylist sa src/shared/constants/upstreamHeaders.ts
7. I-encrypt ang mga credential habang nakaimbak — AES-256-GCM sa pamamagitan ng src/lib/db/encryption.ts
8. Mga pampublikong upstream OAuth identifier sa pamamagitan ng resolvePublicCred() — huwag kailanman mag-embed ng mga literal na AIza… / GOCSPX-… / …apps.googleusercontent.com sa source. Tingnan ang docs/security/PUBLIC_CREDS.md.
9. Mga error response sa pamamagitan ng buildErrorBody() / sanitizeErrorMessage() — huwag kailanman maglagay ng raw na err.stack / err.message sa mga response body ng HTTP / SSE / executor / MCP. Tingnan ang docs/security/ERROR_SANITIZATION.md.
10. Mga runtime value ng exec() / spawn() sa pamamagitan ng opsyong env — huwag kailanman gumamit ng string interpolation para sa mga external path o hindi pinagkakatiwalaang value sa mga script na ipinapasa sa shell. Sanggunian: src/mitm/cert/install.ts::updateNssDatabases.
11. Piliin ang mga library na secure bilang default — tingnan ang tldrsec/awesome-secure-defaults (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). Gamitin muna ang mga ito bago gumawa ng sarili mong solusyon.

Mga natuklasan ng supply-chain scanner (Socket.dev / Snyk / katulad)

Isinasama ng naka-publish na omniroute npm artifact ang Next.js output: "standalone" build, na nangangahulugang ang bawat route handler — kabilang ang mga dokumentadong may-pribilehiyong feature (MITM, Zed import, Cloud Sync, embedded service supervisor) — ay napupunta sa mga naka-minify na chunk ng .next/server/*.js. Madalas na itinutugma ng mga heuristic supply-chain scanner ang mga chunk na iyon sa mga malware signature.

Ang configuration ng scanner na ginagamit namin ay nasa socket.yml sa root ng repository (Socket.dev GitHub App format v2 — tingnan ang https://docs.socket.dev/docs/socket-yml). Tahasan nitong ibinubukod ang mga directory na hindi isinasama sa release (tests/, _tasks/, _references/, _ideia/, _mono_repo/, docs/, atbp.) upang mag-ulat lamang ang scanner tungkol sa mga code path na aktuwal na nakararating sa mga user ng naka-publish na package — ang mismong scan ay pinapatakbo ng Socket GitHub App na nagbabasa sa file na iyon, hindi ng isang workflow sa repository na ito.

Para sa bawat kategorya ng natuklasan, nagpapanatili kami ng pagpapatunay ng maintainer para sa bawat natuklasan:

• docs/security/SOCKET_DEV_FINDINGS.md — mapa para sa bawat natuklasan: source file ↔ na-flag na chunk ↔ gawi ↔ mitigasyong inilapat sa v3.8.6.
• Ang mga SECURITY-AUDITOR-NOTE: block sa source sa bawat na-flag na function ay tumutukoy pabalik sa parehong dokumento.

Para sa mga user na hindi maaaring luwagan ng pipeline ang alerto: mag-build gamit ang OMNIROUTE_BUILD_PROFILE=minimal npm run build. Pinapalitan nito ang apat na sensitibong module ng mga stub na nagbabalik ng HTTP 503 feature-disabled sa runtime, kaya pisikal na wala sa bundle ang mga may-pribilehiyong code path. Tingnan ang docs/security/SOCKET_DEV_FINDINGS.md para sa proseso ng pag-publish.

Mga Sanggunian

• docs/architecture/AUTHZ_GUIDE.md — pipeline ng awtorisasyon
• docs/security/GUARDRAILS.md — framework ng mga guardrail
• docs/security/COMPLIANCE.md — audit log at retention
• docs/security/PUBLIC_CREDS.md — obligadong pattern para sa mga pampublikong upstream credential
• docs/security/ERROR_SANITIZATION.md — obligadong pattern para sa mga error response
• docs/security/SOCKET_DEV_FINDINGS.md — pagpapatunay ng maintainer para sa mga natuklasan ng supply-chain scanner
• docs/architecture/RESILIENCE_GUIDE.md — circuit breaker + cooldown + lockout
• docs/security/STEALTH_GUIDE.md — TLS fingerprinting (legal/etikal na abiso)
• CLAUDE.md — mahihigpit na tuntunin para sa mga AI agent
• tldrsec/awesome-secure-defaults — piniling koleksiyon ng mga library na secure bilang default