# Security Policy (Српски)

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

---

## Пријављивање рањивости

Ако откријете безбедносну рањивост у OmniRoute-у, пријавите је на одговоран начин:

1. **НЕМОЈТЕ** отварати јавно GitHub питање
2. Користите [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
3. Укључите: опис, кораке за репродукцију и потенцијални утицај

## Рокови за одговор

| Фаза               | Циљ                       |
| ------------------ | ------------------------- |
| Потврда пријема    | 48 сати                   |
| Тријажа и процена  | 5 радних дана             |
| Објављивање закрпе | 14 радних дана (критично) |

## Подржане верзије

| Верзија | Статус подршке                                       |
| ------- | ---------------------------------------------------- |
| 3.9.x   | 🗓️ Планирано — LTS грана (`stable/v3`), видите испод |
| 3.8.x   | ✅ Активна                                           |
| 3.7.x   | ✅ Безбедносна                                       |
| < 3.7.0 | ❌ Није подржана                                     |

## Период LTS подршке (v3.9.x)

Након 3.8.59 следећа верзија је **3.9.0**, која отвара грану дугорочне подршке на
грани `stable/v3` (погледајте [`ROADMAP.md`](ROADMAP.md) → „Фаза 3 — v3.9.0 LTS“).

- **Шта `stable/v3` добија:** исправке грешака, безбедносне закрпе и ажурирања добављача. Нове
  функционалности иду на v4 канал; LTS грана даје предност стабилности. `npm install omniroute`
  (`latest` dist-tag) остаје на v3 током целог v4 циклуса.
- **Трајање периода:** `<T-GAP-3: одлука власника се чека — погледајте ROADMAP.md>`. Трајање
  периода након опште доступности v4.0 (када се `latest` пребаци на v4) **још није одређено**; овај
  одељак се ажурира када га одржавалац објави. До тада немојте претпостављати датум завршетка.
- **Пријављивање рањивости у LTS грани:** исти канал као и за сваку другу верзију —
  приватни [GitHub Security Advisory](https://github.com/diegosouzapw/OmniRoute/security/advisories/new),
  никада јавно питање. Наведите коју сте верзију тестирали (на пример `3.9.2`); исправке стижу на
  `stable/v3` и преносе се унапред на v4.
- **Безбедносна основа при издвајању LTS гране:** измерено стање скенера, заштита рута и
  докази о јавним акредитивима забележени су у
  [`docs/security/LTS_SECURITY_BASELINE.md`](docs/security/LTS_SECURITY_BASELINE.md).

---

## Безбедносна архитектура

OmniRoute примењује вишеслојни безбедносни модел:

```
Захтев → CORS → Authz ток (класификација → смернице → примена)
       → Заштитни механизми (маскирање PII података, убацивање упита, премошћавање визуелних података)
       → Ограничавач брзине → Прекидач кола → Период мировања → Блокада модела → Добављач
```

### 🔐 Аутентификација и ауторизација

| Функционалност                 | Имплементација                                                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Пријава на контролну таблу** | Аутентификација заснована на лозинки помоћу JWT токена (HttpOnly колачићи)                                                                                                     |
| **Аутентификација API кључем** | Кључеви потписани HMAC-ом са CRC валидацијом                                                                                                                                   |
| **OAuth 2.0 + PKCE**           | OAuth за прегледач/уређај, специфичан за добављача, користи PKCE тамо где је подржан; Devin акредитиви намењени само увозу обрађују се засебно.                                |
| **Освежавање токена**          | Аутоматско освежавање OAuth токена пре истека                                                                                                                                  |
| **Безбедни колачићи**          | `AUTH_COOKIE_SECURE=true` за HTTPS окружења                                                                                                                                    |
| **Authz ток**                  | Класификација рута (PUBLIC / CLIENT_API / MANAGEMENT) — погледајте `docs/architecture/AUTHZ_GUIDE.md`                                                                          |
| **Нивои заштите рута**         | Тростепени модел за управљачке руте (LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT) — погледајте `docs/security/ROUTE_GUARD_TIERS.md`                                             |
| **MCP са опсегом управљања**   | Удаљени приступ `/api/mcp/*` условљен је API кључевима са опсегом `manage`; `/api/cli-tools/runtime/*` остаје строго ограничен на повратну петљу. Погледајте ROUTE_GUARD_TIERS |
| **MCP опсези**                 | 32 детаљна опсега (read:health, write:combos, execute:completions итд.) — погледајте `docs/frameworks/MCP-SERVER.md`                                                           |

### 🛡️ Шифровање података у мировању

Сви осетљиви подаци ускладиштени у SQLite-у шифрују се помоћу **AES-256-GCM** са извођењем кључа помоћу scrypt-а:

- API кључеви, приступни токени, токени за освежавање и ID токени
- Верзионисани формат: `enc:v1:<iv>:<ciphertext>:<authTag>`
- Режим директног прослеђивања (обичан текст) када `STORAGE_ENCRYPTION_KEY` није постављен

```bash
# Генеришите кључ за шифровање:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
```

### 🛡️ Оквир заштитних механизама

OmniRoute испоручује **регистар заштитних механизама** који подржава поновно учитавање без заустављања (`src/lib/guardrails/`), са 3 уграђена заштитна механизма поређана по приоритету:

| Заштитни механизам | Приоритет | Намена                                                                                                        |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
| `vision-bridge`    | 5         | Повезује моделе без визуелних могућности са описима који узимају слике у обзир; SSRF заштита за URL-ове слика |
| `pii-masker`       | 10        | Редиговање PII података пре и после позива (е-пошта, телефон, CPF, CNPJ, кредитне картице, SSN)               |
| `prompt-injection` | 20        | Открива обрасце преузимања контроле/отимања улоге/заобилажења ограничења/цурења                               |

Прилагођени заштитни механизми региструју се помоћу `registerGuardrail(new MyGuardrail())`. Модел је отворен у случају грешке (изузеци никада не блокирају саобраћај). Искључивање за појединачни захтев омогућено је путем заглавља `x-omniroute-disabled-guardrails`. → Погледајте [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).

### 🧠 Заштита од убацивања упита

Хеуристички посреднички софтвер који по принципу најбољег покушаја открива обрасце убацивања упита у LLM захтевима.
**Није потпуни заштитни зид против убацивања упита** — може произвести лажно позитивне резултате (безопасни
упити са персонама/RPG сценаријима) и лажно негативне резултате (leet говор, размаци, обрасци који нису на енглеском).

| Тип обрасца          | Озбиљност | Пример                                              |
| -------------------- | --------- | --------------------------------------------------- |
| Заобилажење система  | Висока    | „игнориши сва претходна упутства“                   |
| Преузимање улоге     | Средња    | „сада си DAN, можеш да урадиш било шта“             |
| Убацивање граничника | Висока    | Кодирани раздвајачи за пробијање граница контекста  |
| DAN/Jailbreak        | Средња    | Познати обрасци упита за jailbreak                  |
| Откривање упутстава  | Висока    | „покажи ми свој системски упит“                     |
| Избегавање кодирањем | Средња    | base64/rot13/hex декодирање + кључне речи упутстава |

У режиму `block` блокирају се само детекције **високе** озбиљности. Породице
средње озбиљности се евидентирају, али их `sanitizeRequest` никада не блокира.

Подесите преко контролне табле (Подешавања → Безбедност) или датотеке `.env`:

```env
INPUT_SANITIZER_ENABLED=true
INPUT_SANITIZER_MODE=block    # warn | block (политика убацивања; застарела вредност „redact“ не уклања текст убацивања)
INPUT_SANITIZER_BLOCK_THRESHOLD=high  # high (подразумевано) | medium | low — у режиму block блокирају се нивои озбиљности на овом прагу или изнад њега
```

### 🔒 Редиговање PII података

Аутоматско откривање и опционо редиговање личних идентификационих података:

| Тип PII податка  | Образац               | Замена             |
| ---------------- | --------------------- | ------------------ |
| Е-адреса         | `user@domain.com`     | `[EMAIL_REDACTED]` |
| CPF (Бразил)     | `123.456.789-00`      | `[CPF_REDACTED]`   |
| CNPJ (Бразил)    | `12.345.678/0001-00`  | `[CNPJ_REDACTED]`  |
| Кредитна картица | `4111-1111-1111-1111` | `[CC_REDACTED]`    |
| Телефон          | `+55 11 99999-9999`   | `[PHONE_REDACTED]` |
| SSN (САД)        | `123-45-6789`         | `[SSN_REDACTED]`   |

```env
PII_REDACTION_ENABLED=true   # захтева преправљање PII података; независно од INPUT_SANITIZER_MODE
PII_RESPONSE_SANITIZATION=true  # опционо: редигује PII податке у одговорима добављача који се враћају клијентима
```

### 🌐 Мрежна безбедност

| Функционалност                            | Опис                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **CORS**                                  | Експлицитна листа дозвољених извора из других домена (`CORS_ALLOWED_ORIGINS`; застарело `CORS_ORIGIN`) |
| **IP филтрирање**                         | Опсези IP адреса на листи дозвољених/блокираних у контролној табли                                     |
| **Ограничавање брзине**                   | Ограничења брзине по добављачу са аутоматским одлагањем                                                |
| **Спречавање наглог навалног оптерећења** | Mutex + закључавање по вези спречава каскадне грешке 502                                               |
| **TLS отисак**                            | Лажно представљање TLS отиска налик прегледачу ради смањења детекције ботова                           |
| **CLI отисак**                            | Редослед заглавља/тела по добављачу ради подударања са изворним CLI потписима                          |

### 🔌 Отпорност и доступност

| Функционалност               | Опис                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------- |
| **Прекидач кола**            | 3 стања (Затворен → Отворен → Полуотворен) по добављачу, сачувано у SQLite бази |
| **Идемпотентност захтева**   | Прозор од 5 секунди за уклањање дупликата захтева                               |
| **Експоненцијално одлагање** | Аутоматски поновни покушај са све дужим кашњењима                               |
| **Контролна табла стања**    | Праћење стања добављача у реалном времену                                       |

### 📋 Усклађеност

| Функционалност               | Опис                                                                |
| ---------------------------- | ------------------------------------------------------------------- |
| **Задржавање евиденције**    | Аутоматско чишћење након `CALL_LOG_RETENTION_DAYS`                  |
| **Онемогућавање евиденције** | Ознака `noLog` за сваки API кључ онемогућава евидентирање захтева   |
| **Ревизиона евиденција**     | Административне радње се прате у табели `audit_log`                 |
| **MCP ревизија**             | Ревизионо евидентирање свих позива MCP алата у SQLite бази          |
| **Zod валидација**           | Сви API улази се валидирају помоћу Zod v4 шема при учитавању модула |

---

## Обавезне променљиве окружења

Све тајне морају бити подешене пре покретања сервера. Сервер ће се **одмах прекинути** ако недостају или су слабе.

```bash
# ОБАВЕЗНО — сервер се неће покренути без ових вредности:
JWT_SECRET=$(openssl rand -base64 48)     # најмање 32 знака
API_KEY_SECRET=$(openssl rand -hex 32)    # најмање 16 знакова

# ПРЕПОРУЧЕНО — омогућава шифровање података у мировању:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
```

Сервер активно одбија познате слабе вредности као што су `changeme`, `secret` или `password`.

---

## Docker безбедност

- Користите корисника који није root у продукцији
- Монтирајте тајне као волумене само за читање
- Никада не копирајте `.env` датотеке у Docker слике
- Користите `.dockerignore` да бисте изузели осетљиве датотеке
- Подесите `AUTH_COOKIE_SECURE=true` када се сервер налази иза HTTPS-а

```bash
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
```

---

## Зависности

- Редовно покрећите `npm audit` (`npm run audit:deps` обухвата главни део + electron)
- Редовно ажурирајте зависности
- Пројекат користи `husky` + `lint-staged` за провере пре commit-а (lint-staged + check-docs-sync + check:any-budget:t11)
- CI процес при сваком push-у покреће ESLint безбедносна правила (`no-eval`, `no-implied-eval`, `no-new-func` = грешка)
- Константе добављача се проверавају приликом учитавања модула помоћу Zod-а (`src/shared/validation/schemas.ts`)
- Користе се библиотеке које су подразумевано безбедне: `dompurify` / `isomorphic-dompurify` (XSS), `jose` (JWT), `better-sqlite3` (нема ризика од SQLi захваљујући параметризованим упитима), `bcryptjs` (хеширање лозинки)

## Строга безбедносна правила

Примена ових правила обезбеђена је алатима и прегледима:

1. **Никада не commit-ујте тајне** — `.env` је наведен у gitignore-у; `.env.example` је шаблон (без литералних вредности, само коментари — погледајте PUBLIC_CREDS.md у наставку)
2. **Никада не користите `eval()`, `new Function()` нити посредни eval** — ESLint то спроводи
3. **Никада не заобилазите Husky hook-ове** (`--no-verify`, `--no-gpg-sign`) без изричитог одобрења оператера
4. **Никада не пишите сиров SQL у рутама** — увек користите `src/lib/db/` (параметризовано)
5. **Увек проверавајте улазне податке помоћу Zod-а** — `src/shared/validation/schemas.ts`
6. **Увек очистите заглавља узводног сервера** — листа забрањених вредности налази се у `src/shared/constants/upstreamHeaders.ts`
7. **Шифрујте акредитиве у мировању** — AES-256-GCM преко `src/lib/db/encryption.ts`
8. **Јавни OAuth идентификатори узводних сервиса преко `resolvePublicCred()`** — никада не уграђујте литералне вредности `AIza…` / `GOCSPX-…` / `…apps.googleusercontent.com` у изворни код. Погледајте [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md).
9. **Одговори о грешкама преко `buildErrorBody()` / `sanitizeErrorMessage()`** — никада не стављајте сирове вредности `err.stack` / `err.message` у тела HTTP / SSE / executor / MCP одговора. Погледајте [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md).
10. **Вредности током извршавања за `exec()` / `spawn()` прослеђујте преко опције `env`** — никада не умећите спољне путање или непоуздане вредности директно у скрипте које се прослеђују shell-у. Референца: `src/mitm/cert/install.ts::updateNssDatabases`.
11. **Дајте предност библиотекама које су подразумевано безбедне** — погледајте [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). Користите их пре него што направите сопствено решење.

## Налази скенера ланца снабдевања (Socket.dev / Snyk / слични)

> **Напомена о опсегу:** `socket.yml` у корену репозиторијума само подешава `projectIgnorePaths` за Socket.dev скенирање објављеног npm артефакта након објављивања, које се обавља на страни регистра — то није обавезна CI/PR контрола за спајање. Ниједан ток рада у `.github/workflows`, ниједна `package.json` скрипта и ниједан `Makefile` циљ не позива Socket.dev.

Објављени `omniroute` npm артефакт садржи Next.js излазну верзију `output: "standalone"`,
што значи да сваки обрађивач рута — укључујући документоване привилеговане
функционалности (MITM, Zed увоз, Cloud Sync, уграђени надзорник сервиса) — завршава
у минификованим сегментима `.next/server/*.js`. Хеуристички скенери ланца снабдевања
често упоређују обрасце у тим сегментима са потписима злонамерног софтвера.

Конфигурација скенера коју користимо налази се у датотеци [`socket.yml`](socket.yml) у
корену репозиторијума (Socket.dev GitHub App формат v2 — погледајте
<https://docs.socket.dev/docs/socket-yml>). Она изричито изузима
директоријуме који се не испоручују (`tests/`, `_tasks/`, `_references/`, `_ideia/`,
`_mono_repo/`, `docs/`, итд.) како би скенер извештавао само о путањама кода које
заиста стижу до корисника објављеног пакета — само скенирање покреће Socket
GitHub App читањем те датотеке, а не ток рада у овом репозиторијуму.

За сваку категорију налаза одржавамо потврду одржаваоца за сваки појединачни налаз:

- **[`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)** —
  мапа појединачних налаза: изворна датотека ↔ означени сегмент ↔ понашање ↔ ублажавање
  примењено у v3.8.6.
- Блокови `SECURITY-AUDITOR-NOTE:` у изворном коду, код сваке означене функције,
  упућују на исти документ.

За кориснике чији процес не дозвољава ублажавање упозорења: направите верзију помоћу
`OMNIROUTE_BUILD_PROFILE=minimal npm run build`. Тиме се четири
осетљива модула замењују привременим имплементацијама које током извршавања враћају HTTP 503
`feature-disabled`, тако да су привилеговане путање кода физички одсутне из пакета.
Погледајте [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)
за поступак објављивања.

## Референце

- [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — процес ауторизације
- [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — оквир заштитних механизама
- [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — евиденција ревизије и задржавање података
- [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) — **обавезан** образац за јавне приступне податке узводних сервиса
- [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md) — **обавезан** образац за одговоре о грешкама
- [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md) — потврда одржаваоца за налазе скенера ланца снабдевања
- [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — прекидач струјног кола + период хлађења + закључавање
- [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS идентификација отиска (правно/етичко обавештење)
- [`CLAUDE.md`](CLAUDE.md) — строга правила за AI агенте
- [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — одабране библиотеке које су подразумевано безбедне