yusufkhon-guard 1.0.0

package/README.md

@@ -0,0 +1,734 @@
+# 🛡️ yusufkhon-guard
+
+> Express.js va Node.js serverlari uchun **yengil**, **mustaqil (zero-dependency)** xavfsizlik va middleware kutubxonasi.
+
+`yusufkhon-guard` serverga kelayotgan HTTP so'rovlarni avtomatik filtrlaydi, zamonaviy xavfsizlik sarlavhalarini o'rnatadi, IP bo'yicha so'rovlarni cheklaydi (DoS/Brute-force himoyasi), kiruvchi ma'lumotlarni tozalaydi (XSS / SQLi) hamda **"blue team" aktiv himoya** orqali hujumlarni real vaqtda aniqlab, hujum manbasini avtomat bloklaydi. Bundan tashqari, o'rnatilgan **audit-skaner** serveringizni tekshirib, SSL/domen va konfiguratsiya muammolarini topadi va xavfsiz tuzatishlarni avtomat bajaradi.
+
+[![npm version](https://img.shields.io/badge/npm-1.0.0-red)](https://www.npmjs.com/package/yusufkhon-guard)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#)
+
+---
+
+## ✨ Asosiy imkoniyatlar
+
+| Modul | Vazifasi |
+| :--- | :--- |
+| 🔥 **Firewall (Blue Team)** | Har bir so'rovni real vaqtda tahlil qiladi, hujum (SQLi/XSS/skaner/traversal) sezilsa **IP'ni avtomat bloklaydi** va hodisani signalizatsiya qiladi |
+| 🧢 **Security Headers** | `X-Frame-Options`, `X-Content-Type-Options`, `X-XSS-Protection`, `Strict-Transport-Security`, `Content-Security-Policy`, `X-Powered-By` |
+| ⏱️ **Rate Limiter** | Bitta IP'dan kelgan ortiqcha so'rovlarga `429 Too Many Requests` qaytaradi (Memory Store) |
+| 🧼 **Sanitizer** | `req.body`, `req.query`, `req.params` dagi `<script>` teglari va shubhali kontentni tozalaydi |
+| 🔍 **Audit Scanner** | SSL/domen, xavfsizlik sarlavhalari, muhit va bog'liqliklarni tekshiradi; xavfsiz muammolarni avtomat tuzatadi |
+| 🔐 **Consent Layer** | Root/admin talab qiladigan amallarni rozilik so'rab, `sudo`/UAC tasdig'i bilan bajaradi — hech qachon jimgina emas |
+| 🧱 **OS Firewall** | Zararli IP'ni tizim firewall'ida (`ufw`/`iptables`/`netsh`) bloklaydi |
+| 📊 **Live Dashboard** | Bloklangan IP va hodisalarni real vaqtda (SSE) ko'rsatuvchi web admin-panel |
+| 📜 **ACME / Let's Encrypt** | Domen uchun bepul SSL sertifikatini to'liq avtomat oladi (native, zero-dep) |
+| 🌊 **L7 DDoS himoyasi** | Global RPS anomaliya + "Under Attack Mode" + concurrency + load-shedding + cookie-challenge + Slowloris himoyasi |
+| 🌍 **Geo-IP / Anti-VPN** | Davlat bo'yicha filtrlash + datacenter/VPN (AWS, Hetzner, OVH…) IP'larini bloklash |
+| 🧠 **Adaptive Rate-Limit** | Xatti-harakatga qarab limitni avtomat qattiqlashtiradi (brute-force/burst) |
+| 🤖 **Bot / JA3 Fingerprint** | Brauzer vs skript (curl/python) ni HTTP va TLS (JA3) darajasida ajratadi |
+| 🍯 **HoneyPot** | Soxta tuzoq yo'llar (`/.env`, `/wp-login.php`) — tushgan IP darhol bloklanadi |
+| 🧬 **NoSQL / CSRF / BodyLimit** | NoSQL-injection, JSON-pollution, CSRF va katta payload (DoS) himoyasi |
+| 🔬 **File Integrity (FIM)** | Muhim fayllar buzilsa (backdoor) hash orqali sezib ogohlantiradi |
+| 🔔 **Real-Time Alerts** | Telegram / Discord / Webhook orqali instant ogohlantirish + JSON/SIEM log eksport |
+| 🔒 **HTTPS Redirect** | HTTP so'rovlarni avtomatik HTTPS'ga yo'naltiradi (301) |
+| 📝 **Logger** | Bloklangan IP va xavfsizlik hodisalarini rangli konsol / fayl loglariga yozadi |
+
+- ✅ **0 ta tashqi kutubxona** — faqat Node.js standart modullaridan foydalanadi.
+- ✅ **Modulli** — barcha modullarni birga yoki alohida ishlatish mumkin.
+- ✅ **To'liq sozlanuvchi** — har bir modulning o'z parametrlari bor.
+
+---
+
+## 📦 O'rnatish
+
+```bash
+npm install yusufkhon-guard
+```
+
+> `express` — peer dependency. Agar loyihangizda hali bo'lmasa:
+>
+> ```bash
+> npm install express
+> ```
+
+---
+
+## 🚀 Tezkor boshlash
+
+Eng oddiy usul — barcha himoya qatlamlarini bitta `guard()` bilan ulash:
+
+```js
+const express = require('express');
+const guard = require('yusufkhon-guard');
+
+const app = express();
+app.use(express.json());
+
+// Barcha himoya modullarini standart sozlamalar bilan ulaymiz.
+app.use(guard());
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Xavfsiz server ishlayapti!' });
+});
+
+app.listen(3000, () => console.log('Server: http://localhost:3000'));
+```
+
+Tayyor! Endi serveringiz avtomatik ravishda himoyalangan. 🎉
+
+---
+
+## ⚙️ Sozlash (Configuration)
+
+`guard()` funksiyasiga har bir modul uchun alohida sozlamalar berish mumkin.
+Biror modulni butunlay o'chirish uchun uning qiymatini `false` qiling.
+
+```js
+app.use(
+  guard({
+    headers: {
+      contentSecurityPolicy: "default-src 'self'",
+      hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+    },
+    rateLimit: {
+      windowMs: 60 * 1000, // 1 daqiqa
+      max: 50,             // har IP uchun daqiqasiga 50 so'rov
+    },
+    sanitize: {
+      blockOnDetection: true, // shubhali so'rovni 400 bilan rad etadi
+    },
+  })
+);
+
+// Biror modulni o'chirish:
+// app.use(guard({ rateLimit: false }));
+```
+
+---
+
+## 🧩 Modullardan alohida foydalanish
+
+Kerak bo'lsa, har bir middleware'ni mustaqil ravishda ulashingiz mumkin —
+masalan, rate-limiter'ni faqat `/api` yo'liga qo'yish:
+
+```js
+const {
+  securityHeaders,
+  rateLimiter,
+  sanitizer,
+} = require('yusufkhon-guard');
+
+// Global xavfsizlik sarlavhalari
+app.use(securityHeaders());
+
+// Faqat /api uchun qattiqroq rate-limit
+app.use('/api', rateLimiter({ windowMs: 60000, max: 20 }));
+
+// Kiruvchi ma'lumotlarni tozalash
+app.use(sanitizer());
+```
+
+---
+
+## 🔥 "Blue Team" aktiv himoya (Firewall)
+
+Bu — kutubxonaning eng kuchli qismi. `guard()` ichiga o'rnatilgan **firewall** har bir
+so'rovni real vaqtda tahlil qiladi (`threatDetector`), tahdid ballini hisoblaydi va
+chegara oshganda hujum kelayotgan **IP'ni avtomat bloklaydi** (`ipBlocker`) — xuddi
+blue-team etik-haker kabi. Bloklar **progressiv**: 5 daqiqa → 1 soat → 24 soat → doimiy.
+
+```js
+const guard = require('yusufkhon-guard');
+
+const shield = guard({
+  firewall: {
+    banThreshold: 100,        // shu ball to'plansa bloklanadi
+    instantBanScore: 80,      // bitta so'rovda 80+ bo'lsa darhol blok
+    strikeWindowMs: 600000,   // ballar to'planadigan oyna (10 daqiqa)
+    whitelist: ['127.0.0.1'], // ishonchli IP'lar (hech qachon bloklanmaydi)
+    persistPath: './logs/bans.json', // bloklar restartda saqlanadi
+  },
+});
+
+app.use(shield);
+
+// AKS-TA'SIR: IP bloklanganda o'zingizning reaksiyangizni ulang
+// (masalan, Telegram / Email / Webhook orqali ogohlantirish yuborish).
+shield.firewall.on('ban', ({ ip, reason }) => {
+  console.log(`🚨 Bloklandi: ${ip} — ${reason}`);
+  // sendTelegramAlert(`Hujum aniqlandi! ${ip} bloklandi.`);
+});
+
+shield.firewall.on('threat', ({ ip, report }) => {
+  // Har bir tahdid signali (bloklamasa ham) shu yerga keladi
+});
+```
+
+**Chiqariladigan hodisalar (events):**
+
+| Hodisa | Ma'lumot | Qachon |
+| :--- | :--- | :--- |
+| `threat` | `{ ip, report, req }` | Har qanday tahdid signali aniqlanganda |
+| `ban` | `{ ip, reason, record }` | IP avtomat bloklanганda |
+| `blocked` | `{ ip, path }` | Bloklangan IP qayta uringanda |
+| `tick` | `stats` | Har `monitorIntervalMs` da (24/7 monitoring) |
+
+**Bloklarni boshqarish (masalan, admin panel uchun):**
+
+```js
+shield.firewall.blocker.listBanned();   // hozir bloklangan IP'lar
+shield.firewall.blocker.unban('1.2.3.4'); // blokni olib tashlash
+shield.firewall.blocker.allow('5.6.7.8'); // oq ro'yxatga qo'shish
+shield.firewall.blocker.stats();          // { tracked, banned }
+```
+
+Aniqlanadigan hujum turlari: **SQL Injection, XSS, Path Traversal, Command Injection,
+zararli skanerlar** (sqlmap, nikto, nmap, nuclei…), shubhali manzillar (`/.env`, `/.git`,
+`/wp-admin`) va h.k.
+
+---
+
+## 🔍 Audit-skaner (Security Scanner)
+
+Kutubxonani o'rnatgach, serveringizni bitta buyruq bilan skanerlashingiz mumkin.
+Skaner **SSL sertifikati, domen, xavfsizlik sarlavhalari, muhit (NODE_ENV, `.env`),
+bog'liqliklar** va boshqalarni tekshiradi, so'ng chiroyli hisobot va xavfsizlik bahosini
+(0–100) beradi.
+
+### Terminal orqali (CLI)
+
+```bash
+# To'liq skanerlash
+npx yusufkhon-guard scan --domain mysite.uz --target http://localhost:3000
+
+# Xavfsiz muammolarni avtomat tuzatish bilan
+npx yusufkhon-guard scan --fix
+
+# yoki loyihada
+npm run scan
+```
+
+### Kod ichida (dasturiy)
+
+```js
+const { scan, formatReport } = require('yusufkhon-guard');
+
+const result = await scan({
+  domain: 'mysite.uz',              // SSL/sertifikat tekshiruvi
+  target: 'http://localhost:3000',  // ishlab turgan server sarlavhalari
+  autoFix: true,                    // xavfsiz muammolarni avtomat tuzatadi
+});
+
+console.log(formatReport(result));
+console.log(result.score);   // masalan: 87
+console.log(result.summary); // { critical, high, medium, low, info, ok }
+```
+
+> **Halol eslatma:** Skaner **xavfsiz** tuzatishlarni (masalan, `.env` ni `.gitignore` ga
+> qo'shish) avtomat bajaradi. SSL sertifikatini butunlay o'rnatish esa tizim darajasidagi
+> huquq (root/`certbot`) talab qiladi — shuning uchun skaner muammoni aniqlaydi va aniq
+> buyruqni (`sudo certbot --nginx -d domain`) ko'rsatib beradi.
+
+---
+
+## 🔐 Root/Admin rozilik qatlami (Consent Layer)
+
+Ba'zi tuzatishlar (SSL o'rnatish, IP'ni **tizim firewall'ida** bloklash) `root`/administrator
+huquqini talab qiladi. `yusufkhon-guard` bunday amalni **hech qachon jimgina bajarmaydi** —
+u **ikki bosqichli rozilik** so'raydi:
+
+1. **Kutubxonaning o'z so'rovi** — nima va nima uchun bajarilishini ko'rsatib, `[y/N]` so'raydi.
+2. **Operatsion tizim tasdig'i** — Linux/macOS'da `sudo` paroli, Windows'da esa **UAC oynasi**.
+
+```
+  ┌─ 🔐 Privilegiyali amal so'rovi ────────────────────
+  │  Maqsad : example.com uchun Let's Encrypt SSL sertifikatini o'rnatish
+  │  Buyruq : certbot --nginx -d example.com
+  │  Huquq  : UAC orqali so'raladi
+  └────────────────────────────────────────────────────
+  ❓ Ushbu amalni bajarishga ruxsat berasizmi? [y/N]
+```
+
+> Interaktiv terminal bo'lmasa (CI/skript), privilegiyali amal **standart holatda RAD etiladi**.
+> Ataylab `--yes` (yoki `autoApprove: true`) berilgandagina bajariladi.
+
+### IP'ni OS firewall'ida bloklash (haqiqiy blue team)
+
+Node.js ilovasi ichida bloklashdan tashqari, zararli IP'ni **tarmoq/OS darajasida** ham
+uzib qo'yish mumkin — shunda hujum Node.js'gacha ham yetib kelmaydi:
+
+```js
+const { osFirewall } = require('yusufkhon-guard');
+
+// Linux -> ufw/iptables, Windows -> netsh advfirewall (rozilik + sudo/UAC bilan)
+await osFirewall.block('66.66.66.66');           // rozilik so'raydi
+await osFirewall.block('66.66.66.66', { dryRun: true }); // faqat ko'rsatadi
+await osFirewall.unblock('66.66.66.66');
+```
+
+Buni firewall'ning `ban` hodisasiga ulab, **avtomat aks-ta'sir** yasashingiz mumkin:
+
+```js
+const guard = require('yusufkhon-guard');
+const { osFirewall } = guard;
+
+const shield = guard({ firewall: { /* ... */ } });
+app.use(shield);
+
+shield.firewall.on('ban', async ({ ip }) => {
+  // DIQQAT: server root bilan ishlayotgan bo'lsagina autoApprove maʼqul.
+  await osFirewall.block(ip, { autoApprove: true });
+});
+```
+
+> Xavfsizlik eslatmasi: ishlab turgan serverda `autoApprove: true` faqat jarayon allaqachon
+> kerakli huquqqa ega bo'lsa ishlaydi. Aks holda buyruq faqat log qilinadi — chunki
+> kutubxona **ruxsatsiz kuchaytirilgan (elevated) amalni bajarmaydi**.
+
+---
+
+## 📊 Real vaqtli admin-panel (Dashboard)
+
+Bloklangan IP'lar, jonli tahdid hodisalari va statistikani **real vaqtda** (Server-Sent
+Events orqali) ko'rsatuvchi web-panel. Express ilovangizga bitta middleware sifatida ulanadi.
+
+```js
+const guard = require('yusufkhon-guard');
+
+const shield = guard({ firewall: { /* ... */ } });
+app.use(shield);
+
+// Panelni token bilan himoyalab ulaymiz
+app.use('/admin', guard.dashboard({
+  firewall: shield.firewall,
+  token: process.env.GUARD_TOKEN,  // maxfiy token
+  title: 'Mening serverim',
+}));
+```
+
+Brauzerda oching: **`http://localhost:3000/admin/?token=SIZNING_TOKEN`**
+
+Panel imkoniyatlari:
+- 📈 Jonli sanoqlar: so'rovlar, tahdidlar, bloklashlar, hozir bloklanganlar, uptime.
+- ⚡ **Real vaqtli hodisalar oqimi** (SSE) — har bir tahdid/blok darhol ko'rinadi.
+- 🚫 Bloklangan IP'lar jadvali + bitta tugma bilan **blokdan chiqarish**.
+- ➕ IP'ni **qo'lda bloklash** yoki oq ro'yxatga qo'shish.
+- 🌗 Och/tund mavzuga moslashuvchan, mobil-do'st dizayn.
+
+**API endpointlari** (barchasi `token` talab qiladi):
+
+| Yo'l | Metod | Vazifasi |
+| :--- | :--- | :--- |
+| `/api/stats` | GET | Statistika |
+| `/api/bans` | GET | Bloklangan IP'lar |
+| `/api/events` | GET | Real vaqt oqimi (SSE) |
+| `/api/block/:ip` | POST | IP'ni qo'lda bloklash |
+| `/api/unban/:ip` | POST | Blokdan chiqarish |
+| `/api/allow/:ip` | POST | Oq ro'yxatga qo'shish |
+
+> ⚠️ Panelni ishlab chiqarishda **HTTPS orqasida** va kuchli token bilan (yoki qo'shimcha
+> autentifikatsiya bilan) oching. Token faqat asosiy himoya qatlamidir.
+
+---
+
+## 📜 ACME — bepul SSL sertifikatini avtomat olish (Let's Encrypt)
+
+To'liq **native** ACME v2 (RFC 8555) mijozi — tashqi kutubxonasiz, faqat Node ichki
+`crypto` va `fetch` yordamida. Domen uchun **bepul SSL sertifikatini avtomat oladi**
+(HTTP-01 challenge).
+
+### ⚡ Eng oson yo'l: bitta buyruq (kod yozmasdan)
+
+`ssl` CLI buyrug'i o'zi vaqtinchalik server ochib, sertifikatni oladi va saqlaydi
+(certbot kabi "standalone" rejim). **Domenni ham o'zi aniqlaydi** (nginx/apache/hostname'dan)
+va admin'ga ko'rsatib tasdiq so'raydi:
+
+```bash
+# Domenni AVTOMAT aniqlaydi -> tasdiq so'raydi -> cert oladi
+sudo npx yusufkhon-guard ssl
+
+# Yoki domenni qo'lda ko'rsatib
+npx yusufkhon-guard ssl --domain sayt.uz --email admin@sayt.uz
+npx yusufkhon-guard ssl --domain sayt.uz,www.sayt.uz --production   # jonli cert
+npx yusufkhon-guard ssl --domain sayt.uz --port 8080               # reverse-proxy orqasida
+```
+
+Natija: `./certs/fullchain.pem` va `./certs/privkey.pem`.
+**Shartlar:** real ommaviy domen, DNS shu serverga yo'naltirilgan, 80-port ochiq.
+
+### 🔄 Avtomat yangilash (renewal) — "o'rnatib unut"
+
+LE sertifikati 90 kunda tugaydi. `renew` buyrug'i tekshiradi va kerak bo'lsa yangilaydi;
+`--install` esa har kunlik avtomat yangilashni (cron/systemd/schtasks) **rozilik so'rab** o'rnatadi:
+
+```bash
+npx yusufkhon-guard renew                  # <30 kun qolsa yangilaydi
+npx yusufkhon-guard renew --force          # majburan yangilaydi
+sudo npx yusufkhon-guard renew --install   # har kuni 03:00 da avtomat yangilashni o'rnatadi
+```
+Bir marta `--install` qilsangiz — keyin sertifikat o'zi yangilanib turadi.
+
+### Yoki dasturiy (Express ichida)
+
+```js
+const express = require('express');
+const acme = require('yusufkhon-guard').acme;
+
+const app = express();
+const store = new acme.ChallengeStore();
+
+// 1) Challenge middleware'ni GUARD'DAN OLDIN ulang (LE tekshiruvi yetib borishi uchun)
+app.use(acme.challengeMiddleware(store));
+
+// ... qolgan middleware va marshrutlar ...
+app.listen(80); // HTTP-01 uchun 80-port ochiq bo'lishi shart
+
+// 2) Sertifikatni oling (avval STAGING'da sinab ko'ring!)
+const result = await acme.obtainCertificate({
+  domains: ['example.com', 'www.example.com'],
+  email: 'admin@example.com',
+  challengeStore: store,
+  environment: 'staging',       // sinovdan o'tgach -> 'production'
+  certDir: './certs',
+  accountKeyPath: './certs/account.pem',
+});
+
+console.log(result.paths); // { fullchain: './certs/fullchain.pem', privkey: './certs/privkey.pem' }
+```
+
+So'ng olingan sertifikat bilan HTTPS serverni ishga tushirasiz:
+
+```js
+const https = require('https');
+const fs = require('fs');
+
+https.createServer({
+  cert: fs.readFileSync('./certs/fullchain.pem'),
+  key: fs.readFileSync('./certs/privkey.pem'),
+}, app).listen(443);
+```
+
+**Muhim shartlar (HTTP-01):**
+- Domen DNS'da shu serverga yo'naltirilgan bo'lishi kerak.
+- 80-port internetdan ochiq bo'lishi kerak (LE `.well-known/acme-challenge/...` ni tekshiradi).
+- Avval `environment: 'staging'` bilan sinang — Let's Encrypt jonli muhitda qat'iy limitlarga ega.
+
+> **Halol eslatma:** Ushbu modulning kriptografik asosi (ES256 JWS imzosi, PKCS#10 CSR)
+> mustaqil sinovdan o'tgan (imzo `openssl` bilan tekshirilgan). Biroq to'liq ketma-ketlik
+> (handshake) haqiqiy, ommaviy domen va ochiq 80-portni talab qiladi — buni o'z domeningizda
+> staging'da sinab ko'ring.
+
+---
+
+## 🌊 L7 (Application Layer) DDoS himoyasi
+
+Oddiy per-IP rate-limit **taqsimlangan** (minglab IP) L7 flood'ni ushlay olmaydi.
+`ddosGuard` buni yaxlit hal qiladi, `connectionGuard` esa **Slowloris/slow-POST**
+hujumlaridan himoya qiladi.
+
+```js
+const guard = require('yusufkhon-guard');
+const http = require('http');
+
+const shield = guard({
+  firewall: {},
+  ddos: {
+    maxRps: 300,           // umumiy RPS oshsa -> "Under Attack Mode"
+    perIpConcurrency: 25,  // bir IP dan bir vaqtdagi maksimal so'rovlar
+    attackPerIpMax: 15,    // Attack Mode'da har IP uchun qattiq limit
+    challenge: true,       // hujum paytida cookie-challenge (oddiy botlarni ajratadi)
+    lagShedMs: 200,        // event-loop lag oshsa -> load shedding (503)
+  },
+});
+app.use(shield);
+
+// Attack Mode hodisalari (dashboard/alert uchun):
+shield.ddos.ddos.on('attack-start', (m) => console.log('🚨 DDoS!', m));
+shield.ddos.ddos.on('attack-end',   ()  => console.log('✅ Normallashdi'));
+
+// Slowloris / slow-POST himoyasi — HTTP serverga biriktiriladi:
+const server = http.createServer(app);
+guard.connectionGuard(server, {
+  headersTimeoutMs: 10000,   // sarlavhalarni sekin yuborishga qarshi
+  requestTimeoutMs: 20000,   // butun so'rovni sekin yuborishga (slow-POST) qarshi
+  idleSocketMs: 10000,       // jim/sekin soketni uzadi (tezkor)
+  maxConnectionsPerIp: 50,   // bir IP dan parallel ulanishlar chegarasi
+});
+server.listen(3000);
+```
+
+**`ddosGuard` nima qiladi:**
+| Mexanizm | Tavsif |
+| :--- | :--- |
+| **Global RPS anomaliya** | Barcha IP'lar bo'yicha umumiy tezlikni kuzatadi (per-IP past bo'lsa ham) |
+| **Under Attack Mode** | Chegara oshsa avtomat yoqiladi; qattiqroq limitlar va challenge qo'llanadi |
+| **Per-IP concurrency** | Bir IP dan bir vaqtda ochiq so'rovlar sonini cheklaydi (429) |
+| **Load shedding** | Event-loop lag oshsa (`perf_hooks`), ortiqcha trafik `503`+`Retry-After` bilan chetlatiladi — server tirik qoladi |
+| **Cookie challenge** | Hujum paytida yengil tekshiruv; brauzer cookie bilan qayta so'raydi va o'tadi, oddiy bot esa yiqiladi |
+| **Firewall integratsiyasi** | Doimiy flooder IP avtomat banlanadi |
+
+> **Sinovdan o'tgan:** L7 himoya jonli serverda haqiqiy hujum bilan sinaldi — 80 ta
+> parallel so'rov (har xil IP) → Attack Mode yoqildi va 71 challenge chiqarildi; bir IP dan
+> 15 parallel so'rov → concurrency bloklandi; Slowloris raw-socket → ~4s da uzildi.
+
+---
+
+## 🧩 Qo'shimcha himoya qatlamlari
+
+Bularning barchasini `guard({...})` ichida bitta joydan yoqish mumkin (opsional —
+sozlama berilgandagina qo'shiladi), yoki har birini alohida `require` qilib ishlatasiz.
+
+```js
+app.use(guard.bodyLimit({ maxBodySize: '512kb' })); // express.json'DAN OLDIN
+
+app.use(guard({
+  geoBlock:    { allowCountries: ['UZ', 'US'], blockDatacenter: true },
+  honeypot:    true,
+  botDetector: { block: true, allowedBots: ['googlebot'] },
+  adaptiveRateLimit: { baseMax: 120, minMax: 15 },
+  csrf:        { allowedOrigins: ['https://mysite.uz'] },
+  nosql:       true,
+  firewall:    {},
+}));
+```
+
+### 🌍 1. Geo-IP va Anti-VPN / Datacenter
+
+```js
+const { geoBlock, datacenterRanges } = require('yusufkhon-guard');
+
+app.use(geoBlock({
+  allowCountries: ['UZ', 'US'],   // faqat shu davlatlar
+  blockDatacenter: true,          // AWS/DO/Hetzner/OVH/GCP/VPN -> 403
+  lookup: (ip) => myGeoLookup(ip), // yoki `geoip-lite` o'rnating
+}));
+
+datacenterRanges.addRanges('AWS', ['3.5.140.0/22']); // rasmiy ranges qo'shish
+```
+
+> Davlat aniqlash uchun `lookup(ip) => 'UZ'` funksiyasini bering yoki ixtiyoriy
+> `npm i geoip-lite` paketini o'rnating (avtomat aniqlanadi). Datacenter/VPN
+> aniqlash esa built-in CIDR ro'yxati bilan **darhol** ishlaydi.
+
+> ⚠️ **XAVFSIZLIK — davlat aniqlanmasa nima bo'ladi (fail-open / fail-closed):**
+> **`allowCountries` (allowlist) rejimida standart holat XAVFSIZ (fail-closed):** agar
+> IP'ning davlati aniqlanmasa (`lookup` `null` qaytarsa) yoki `lookup` xato tashlasa —
+> so'rov **RAD etiladi**. Bu allowlist'ni geo-bazada bo'lmagan IP orqali chetlab
+> o'tishning oldini oladi. **`denyCountries` (denylist) rejimida** esa standart —
+> permissive (noma'lumlar o'tkaziladi). Bu standartlarni ochiq o'zgartirish mumkin:
+> `failClosed: false` (xatoda o'tkazish) va `allowUnknown: true` (noma'lum davlatni
+> o'tkazish). **Diqqat:** qat'iy allowlist'da `failClosed: false` qo'ysangiz, `lookup`
+> ishlamay qolганда himoya **ochilib ketadi** — buni faqat mavjudlik (availability)
+> xavfsizlikdan muhimroq bo'lgan holatlardagina qiling.
+
+### 🧠 2. Aqlli (adaptive) rate-limiting
+
+Odatdagidan boshqacha xatti-harakatni sezib, limitni **avtomat pasaytiradi**:
+juda tez (burst) so'rovlar, yuqori xato (4xx) ulushi yoki `/login` ga bosim.
+
+```js
+const { adaptiveRateLimiter } = require('yusufkhon-guard');
+app.use(adaptiveRateLimiter({ baseMax: 120, minMax: 15, firewall: shield.firewall }));
+```
+
+### 🤖 3. Bot fingerprinting (HTTP + JA3/TLS)
+
+```js
+const { botDetector, ja3 } = require('yusufkhon-guard');
+
+// HTTP darajasi (User-Agent, sec-* sarlavhalari, yo'q sarlavhalar):
+app.use(botDetector({ block: true, allowedBots: ['googlebot', 'bingbot'] }));
+
+// TLS darajasi (JA3) — HTTPS serverda ClientHello'ni "peek" qiladi:
+const tls = require('tls');
+const server = tls.createServer(opts, handler);
+ja3.captureClientHello(server); // endi socket.ja3Hash mavjud
+```
+
+> ⚠️ **JA3 haqida muhim eslatma:** Bu parser **sof RFC-based (RFC 8446/8701)
+> implementatsiya** — sanoat `ja3.io` / Salesforce ja3 vositasi bilan **bevosita
+> solishtirilmagan** (self-consistent, cross-validated emas). Agar production'da
+> ishlatilsa, **real brauzer ClientHello bilan qo'lda cross-validation tavsiya
+> etiladi**. Qo'shimcha cheklovlar (ClientHello fragmentatsiyasi, brauzer versiyalari,
+> JA3 randomizatsiyasi) uchun [CONTRIBUTING.md](CONTRIBUTING.md) dagi "Qo'lda sinalishi
+> shart" bo'limiga qarang.
+
+### 🍯 4. HoneyPot (tuzoq)
+
+```js
+const { honeypot } = require('yusufkhon-guard');
+app.use(honeypot({
+  firewall: shield.firewall,     // tushgan IP darhol bloklanadi
+  osFirewall: guard.osFirewall,  // OS firewall'da ham (ixtiyoriy)
+  osBlock: false,
+  traps: ['/secret-admin'],      // standart tuzoqlarga qo'shimcha
+}));
+```
+Standart tuzoqlar: `/.env`, `/.git/config`, `/wp-login.php`, `/phpmyadmin`, `/config.php` va h.k.
+Bularga so'rov yuborgan **100% bot/hujumchi** — darhol **instant ban**.
+
+### 🧬 5. API xavfsizligi: NoSQL / CSRF / Payload
+
+```js
+const { nosqlGuard, csrf, bodyLimit } = require('yusufkhon-guard');
+
+app.use(bodyLimit({ maxBodySize: '256kb' }));  // express.json'DAN OLDIN — DoS himoyasi
+app.use(express.json());
+app.use(nosqlGuard({ blockOnDetection: true })); // {"$gt":""}, __proto__, chuqur JSON
+app.use(csrf({ allowedOrigins: ['https://mysite.uz'] })); // begona Origin -> 403
+```
+
+### 🔬 6. Fayl yaxlitligi monitoringi (FIM)
+
+```js
+const { IntegrityMonitor } = require('yusufkhon-guard');
+
+const fim = new IntegrityMonitor({
+  files: ['./server.js', './package.json', './src/config.js'],
+  intervalMs: 60000, // har daqiqada tekshiradi
+});
+fim.on('alert', (a) => alerter.send(a)); // buzilsa -> ogohlantirish
+fim.start(); // baseline yaratadi va kuzatishni boshlaydi
+```
+
+### 🔔 7. Real-time ogohlantirish + SIEM log eksport
+
+```js
+const { Alerter, RotatingJsonLogger } = require('yusufkhon-guard');
+
+const alerter = new Alerter({
+  telegramBotToken: process.env.TG_TOKEN,
+  telegramChatId:   process.env.TG_CHAT,
+  discordWebhookUrl: process.env.DISCORD_WH,
+  webhookUrl:       'https://my-siem/ingest',
+});
+alerter.attach(shield.firewall); // ban/threat -> Telegram/Discord/Webhook
+
+// JSON-lines log (Splunk/ELK/Loki uchun) + avtomatik rotatsiya:
+const jsonLog = new RotatingJsonLogger({ filePath: './logs/security.jsonl', maxSize: '10mb', maxFiles: 7 });
+app.use(guard({ logger: jsonLog }));
+```
+
+---
+
+## 📚 API va sozlamalar jadvali
+
+### 1. `securityHeaders(options)`
+
+| Parametr | Turi | Standart | Tavsif |
+| :--- | :--- | :--- | :--- |
+| `frameGuard` | `boolean` | `true` | `X-Frame-Options: DENY` |
+| `noSniff` | `boolean` | `true` | `X-Content-Type-Options: nosniff` |
+| `xssProtection` | `boolean` | `true` | `X-XSS-Protection: 1; mode=block` |
+| `hsts` | `boolean \| object` | `true` | `Strict-Transport-Security` |
+| `contentSecurityPolicy` | `string \| false` | `"default-src 'self'"` | `Content-Security-Policy` |
+| `referrerPolicy` | `string` | `'no-referrer'` | `Referrer-Policy` |
+| `poweredBy` | `string` | `'yusufkhon-guard'` | `X-Powered-By` |
+
+### 2. `rateLimiter(options)`
+
+| Parametr | Turi | Standart | Tavsif |
+| :--- | :--- | :--- | :--- |
+| `windowMs` | `number` | `60000` | Vaqt oynasi (ms) |
+| `max` | `number` | `100` | Oynadagi maksimal so'rovlar soni |
+| `message` | `string` | `"Too Many Requests…"` | Bloklanganda qaytariladigan xabar |
+| `statusCode` | `number` | `429` | HTTP status kodi |
+| `standardHeaders` | `boolean` | `true` | `RateLimit-*` sarlavhalarini qo'shish |
+| `keyGenerator` | `function` | IP bo'yicha | Kalit (IP) aniqlash funksiyasi |
+
+### 3. `sanitizer(options)`
+
+| Parametr | Turi | Standart | Tavsif |
+| :--- | :--- | :--- | :--- |
+| `body` | `boolean` | `true` | `req.body` ni tozalash |
+| `query` | `boolean` | `true` | `req.query` ni tozalash |
+| `params` | `boolean` | `true` | `req.params` ni tozalash |
+| `blockOnDetection` | `boolean` | `false` | Shubhali kontent topilsa `400` qaytarish |
+| `statusCode` | `number` | `400` | Bloklashda status kodi |
+
+### 4. `firewall(options)` — Blue Team
+
+| Parametr | Turi | Standart | Tavsif |
+| :--- | :--- | :--- | :--- |
+| `banThreshold` | `number` | `100` | Bloklash uchun to'planishi kerak bo'lgan ball |
+| `instantBanScore` | `number` | `80` | Bitta so'rovda shu balldan oshsa — darhol blok |
+| `strikeWindowMs` | `number` | `600000` | Ballar to'planadigan oyna (ms) |
+| `whitelist` | `string[]` | `['127.0.0.1','::1']` | Hech qachon bloklanmaydigan IP'lar |
+| `persistPath` | `string \| null` | `null` | Bloklarni saqlash uchun JSON fayl yo'li |
+| `statusCode` | `number` | `403` | Bloklangan IP uchun status kodi |
+| `monitor` | `boolean` | `true` | 24/7 davriy monitoringni yoqish |
+| `monitorIntervalMs` | `number` | `300000` | Monitoring hisoboti oralig'i (ms) |
+
+### 5. `scan(options)` — Audit Scanner
+
+| Parametr | Turi | Standart | Tavsif |
+| :--- | :--- | :--- | :--- |
+| `domain` | `string` | — | SSL/sertifikat tekshiruvi uchun domen |
+| `target` | `string` | — | Sarlavhalar tekshiruvi uchun server URL'i |
+| `cwd` | `string` | `process.cwd()` | Loyiha ildiz papkasi |
+| `autoFix` | `boolean` | `false` | Xavfsiz muammolarni avtomat tuzatish |
+
+---
+
+## 🧪 Sinov (Test)
+
+Loyihada tayyor test serveri mavjud:
+
+```bash
+# 1) express o'rnatilganiga ishonch hosil qiling
+npm install express
+
+# 2) test serverini ishga tushiring
+node test.js
+```
+
+Server ishga tushgach, quyidagilarni sinab ko'ring:
+
+```bash
+# Xavfsizlik sarlavhalarini ko'rish
+curl -i http://localhost:3000/
+
+# Rate limit'ni sinash (11+ marta yuboring -> 429)
+curl -i http://localhost:3000/
+
+# Sanitizer'ni sinash (<script> tozalanadi)
+curl -X POST http://localhost:3000/comment \
+  -H "Content-Type: application/json" \
+  -d '{"text":"<script>alert(1)</script>Salom"}'
+```
+
+---
+
+## 📝 Logger
+
+Kutubxona bloklangan IP va xavfsizlik hodisalarini avtomatik loglaydi.
+O'z logger'ingizni yaratib, fayrga yozishni yoqishingiz mumkin:
+
+```js
+const { Logger, guard } = require('yusufkhon-guard');
+
+const logger = new Logger({
+  prefix: 'my-app',
+  filePath: './logs/security.log', // hodisalar faylga ham yoziladi
+});
+
+app.use(guard({ logger }));
+```
+
+---
+
+## 🛡️ Xavfsizlik bo'yicha eslatma
+
+`yusufkhon-guard` **birlamchi himoya qatlami** sifatida mo'ljallangan.
+To'liq himoya uchun quyidagilar bilan birga ishlatilishi tavsiya etiladi:
+
+- Ma'lumotlar bazasi uchun **parametrlashtirilgan so'rovlar** (prepared statements);
+- Autentifikatsiya va avtorizatsiya;
+- HTTPS (TLS) va ishonchli sessiya boshqaruvi.
+
+---
+
+## 📄 Litsenziya
+
+[MIT](./LICENSE) © Yusufkhon