@inverz/shield
v0.4.0
Published
In-app firewall (WAF + RASP) for Node.js — SQLi, NoSQLi, command/code injection, path traversal, SSRF, XXE, uploads, JWT, CSRF, IDOR, DLP, bots, rate limiting
Readme
@inverz/shield
In-app firewall (WAF + RASP) สำหรับ Node.js — ติดตั้งแบบ npm แล้วป้องกันจากด้านในแอป ใช้ได้กับ Express, Fastify, Koa, NestJS (Express adapter) และ ESM
In-app firewall (WAF + RASP) for Node.js: blocks SQL/NoSQL/command/code injection, path traversal, SSRF, XXE, malicious uploads, JWT and CSRF attacks, IDOR, bots and abuse from inside the app, and masks leaks in responses.
ป้องกันอะไรได้บ้าง
| ชั้น | ป้องกัน |
|---|---|
| Sink hook (RASP) | SQLi (mysql2, mysql, pg, better-sqlite3, node:sqlite) · NoSQLi (mongodb, mongoose) · Command injection (child_process) · Code injection (eval, new Function, vm) · Path traversal (fs, fs.promises) · SSRF (fetch, http(s), net, tls รวมกรณี IP แบบ decimal/hex, DNS ที่ชี้ไป IP ภายใน, redirect) · XXE (libxmljs) |
| Second-order SQLi | ตรวจโครงสร้าง query เอง (tautology, '--, stacked DROP) โดยไม่ต้องรู้ว่า input มาจากไหน |
| Evasion | ถอดรหัส input ก่อนเทียบเสมอ: base64, double URL, \uXXXX, HTML entity, JSON ที่ซ่อนอยู่ใน string |
| Request | ตรวจ body ทุกชนิดแม้ไม่มี parser (JSON, form, multipart, XML, gzip) · Prototype pollution · XSS · Log4Shell · SSTI · XXE signature |
| Upload | magic bytes ไม่ตรงนามสกุล · .php.jpg · polyglot · exe ปลอมเป็นรูป · SVG ที่มี script · zip bomb · zip slip · ชื่อไฟล์ที่มี ../ |
| Auth | JWT แบบ strict (alg:none, algorithm confusion, kid/jku injection, exp/nbf/iss/aud) · CSRF (Origin + Sec-Fetch-Site) · IDOR ข้าม tenant · การไล่ ID (enumeration) |
| Response | บังคับ cookie flags · ปิด CORS ที่ตั้งผิด · open redirect · ซ่อน stack trace และ DB error · mask เลขบัตรประชาชน, บัตรเครดิต, key |
| Traffic | IP จริงหลัง proxy (ปลอม XFF ไม่ได้) · rate limit ตาม IP, user หรือ username · แบน IP อัตโนมัติ · ตามคนร้ายที่เปลี่ยน IP (cloud provider, fingerprint) · 404 flood · scanner และ headless bot · slowloris · body/gzip bomb |
| ความทนทาน | failOpen — ถ้าตัว shield เองพัง แอปยังทำงานต่อได้ · regex มีเพดานความยาว (กัน ReDoS) · cache input ต่อ request |
ติดตั้ง
npm i @inverz/shield// บรรทัดแรกๆ ของแอป — ก่อน require DB driver / routes
const shield = require('@inverz/shield').init({
mode: 'block', // 'block' | 'detect' | 'off'
trustProxy: 1, // Cloud Run = 1, Cloudflare→GCLB = 2, 'cloudflare', ['10.0.0.0/8'], false
rateLimit: {
global: { windowMs: 60_000, max: 600 },
rules: [{ path: '/api/auth/login', method: 'POST', windowMs: 60_000, max: 5, by: ['ip', 'body.email'] }],
},
jwt: { secret: process.env.JWT_SECRET, algorithms: ['HS256'], issuer: 'inverz', required: ['/api/*'] },
csrf: { origins: ['https://app.example.com'] },
cors: { origins: ['https://app.example.com'] },
tenancy: { column: 'tenant_id', tables: ['invoices', 'customers'], getTenant: (req) => req.user?.tenantId },
dlp: { errors: 'mask', stackTraces: 'mask', pii: 'detect' }, // pii: 'mask' ถ้าไม่มีหน้าไหนต้องโชว์เลขบัตรจริง
uploads: { allowedExtensions: ['jpg', 'png', 'pdf', 'xlsx'] },
report: { url: 'https://shield.example.com/api/events', token: process.env.SHIELD_TOKEN, app: 'my-app' },
});
const app = express();
app.use(shield.middleware()); // วางก่อนหรือหลัง body parser ก็ได้
app.use(express.json());
// ...routes
app.use(shield.errorHandler());Fastify: await fastify.register(shield.fastify) · Koa: app.use(shield.koa()) (ให้วางเป็นตัวแรก)
ไม่อยากแก้โค้ด: node -r @inverz/shield/register app.js หรือ ESM node --import @inverz/shield/register.mjs app.mjs (ตั้ง SHIELD_MODE, SHIELD_CONFIG=./shield.config.js ได้) โหมดนี้ตรวจทุก request ที่ระดับ http(s) server ให้เองโดยไม่ต้องใส่ middleware · ถ้าใช้ init() เองแล้วไม่อยากใส่ middleware ให้ตั้ง autoProtect: true
ตอน init() ทำงานจะมีโล่เล็กๆ ขึ้นใน terminal ครั้งเดียว บอกเวอร์ชัน โหมด และ hook ที่ติดอยู่ (สีเขียว = block, เหลือง = detect, เทา = off):
▟███████▙ @inverz/shield v0.4.0 mode: block
██ ✓ ██ hooks: fs · child_process · net/http · eval · mysql2 · pg
▜█████▛ docs https://inverz-npm-package.web.app/shield/ถ้า stderr ไม่ใช่ terminal (Cloud Run, Docker, log file) จะพิมพ์เป็นบรรทัดเดียว [inverz-shield] v0.4.0 mode=block hooks=... แทน · ปิดได้ด้วย init({ banner: false }) หรือ SHIELD_BANNER=0
โล่บนหน้าเว็บ (opt-in): init({ badge: true }) จะแปะโล่เล็กๆ ที่มุมล่างขวาของทุกหน้า HTML ที่แอปตอบกลับ ปกติเห็นแค่ไอคอนโล่ พอเอาเมาส์ชี้ (หรือแตะ/โฟกัส) จะขยายออกพร้อมข้อความ "Protected by Inverz Shield" คลิกแล้วไป https://inverztech.com (เปลี่ยนได้ด้วย link) ปรับได้ด้วย badge: { position: 'bottom-left', theme: 'light', text: 'ปกป้องโดย Shield', link: false }
- ใส่เฉพาะหน้า HTML เต็มที่มี
</body>และ status 2xx · ไม่แตะ JSON, fragment (htmx) หรือ response ที่ gzip แล้ว - เป็น HTML +
<style>เล็กๆ ไม่มี script · ถ้าตั้ง CSPstyle-srcแบบไม่มี'unsafe-inline'โล่จะไม่แสดง
ค่าที่ควรตั้งก่อนขึ้น production
trustProxy: ถ้าอยู่หลัง load balancer ต้องตั้งเสมอ ถ้าไม่ตั้ง ทุกคนจะดูเป็น IP เดียวกัน Shield จึงเตือนใน log และปิด auto-ban กับ global rate limit ไว้ เพื่อไม่ให้ผู้โจมตีคนเดียวทำให้ทุกคนโดนแบน- การบันทึก/บล็อกผิด: ไล่จาก
mode: 'detect'แล้วดู log ก่อนเปลี่ยนเป็นblock·detectไม่บล็อกและไม่แก้ body, cookie หรือ CORS (ยังเติม security headers) ยกเว้นjwt.requiredที่ยังตอบ 401 เสมอ เพราะเป็นการยืนยันตัวตน - ข้อความที่ตั้งใจให้มี HTML/โค้ด (CMS, comment ของ dev): ใช้
exceptionsยกเว้นเฉพาะ route หรือ field แทนการปิดทั้งignorePaths
ยกเว้นได้เฉพาะการตรวจระดับ request (exceptions: [{ path: '/api/posts/*', method: 'POST', skip: ['xss', 'signatures'], fields: ['body.content'] }]xss,signatures,nosql,prototypePollution,uploads,csrf,bots) ส่วน sink hook ยังทำงานเหมือนเดิม - Bot:
bots.blockHeadlessเปิดเป็นค่า default จึงบล็อก Playwright/Puppeteer ด้วย · ถ้ามี e2e test หรือ service สร้าง PDF ให้ใช้bots: { allowUserAgents: ['my-pdf-service'] }หรือblockHeadless: false· ถ้าอยากบล็อกpython-requestsกับGo-http-clientด้วย ให้ตั้งblockGenericClients: true - Cookie: ค่า default เติม
HttpOnlyให้ทุก cookie · cookie ที่ JavaScript ต้องอ่าน (เช่นXSRF-TOKEN) ให้ใส่ในcookies: { exclude: ['XSRF-TOKEN'] } - ขนาด request:
maxBodyBytes(1MB) ใช้กับ body ทั่วไป ส่วน multipart ใช้ค่าที่มากกว่าระหว่างค่านี้กับuploads.maxFileBytes(25MB) และ body ที่กำลังตรวจในหน่วยความจำถูกจำกัดรวมที่maxPeekInFlightBytes(256MB) และต่อ client ที่maxPeekPerIpBytes(64MB) เกินแล้วตอบ 503 ·hardenServer.requestTimeout(60 วินาที) อาจตัด upload ใหญ่บนเน็ตช้า ปรับเพิ่มได้ถ้าจำเป็น
คนร้ายเปลี่ยน IP หนีการแบน
คนร้ายมักเช่าเครื่องบน cloud แล้วเปลี่ยน IP ทุกครั้งที่โดนแบน เช่น โดน denylist ที่ DigitalOcean แล้วย้ายไป Cloud Run ของ Google · ตั้งแบบนี้:
shield.init({
trustProxy: 1,
cloud: {
providers: ['google', 'aws', 'digitalocean', 'oracle', 'linode'], // โหลดรายการ IP ทางการของแต่ละเจ้า อัปเดตทุก 24 ชม.
ignorePaths: ['/webhooks/*'], // route ที่ partner ยิงมาจาก cloud จริง
},
attackWave: { fingerprint: true }, // ถ้าไม่มี mobile app/partner ที่ใช้ HTTP client ตัวเดียวกันจำนวนมาก
bots: { denyUserAgents: ['leeavehub', 'spaxppert'] },
});| ชั้น | ทำงานยังไง |
|---|---|
| cloud.action: 'strict' (default เมื่อตั้ง providers) | IP ของ cloud โจมตี ครั้งเดียว (cloud.threshold) แบนทันที 1 ชม. ส่วน IP บ้าน/มือถือใช้เกณฑ์ปกติ (8 ครั้ง/นาที) |
| cloud.escalate | IP คนละตัวจาก provider เดียวกันโดนแบนหรือติด denylist ครบ 3 ตัวใน 10 นาที → บล็อกทั้ง provider 1 ชม. (event ban ที่มี provider) · ปลดเองด้วย shield.unbanProvider('google') |
| cloud.action: 'block' | บล็อกทุก request จาก cloud เลย เหมาะกับเว็บที่ลูกค้าเป็นคนจริงเท่านั้น · partner ใส่ใน ipAllowlist หรือ cloud.ignorePaths |
| attackWave.fingerprint | ตอนแบนจะจำ user-agent + ลำดับ header + ค่า accept ไว้ด้วย เครื่องมือเดิมมาจาก IP ใหม่ก็โดนแบนทันที · ไม่ใช้กับ browser (มี Sec-Fetch-*) เพราะทุกคนที่ใช้ Chrome มี fingerprint เดียวกัน |
| bots.denyUserAgents | บล็อกชื่อเครื่องมือที่เห็นใน log (string ไม่สนตัวพิมพ์เล็กใหญ่ หรือ RegExp) |
ตัวกันพลาด (cloud.maxShare, default 0.2): ถ้า request ปกติที่ไม่ใช่การโจมตีมาจาก provider ไหนเกิน 20% (และอย่างน้อย 10 ครั้งในช่วง escalate.windowMs) Shield จะไม่บล็อก provider นั้นทั้งก้อน และใช้เกณฑ์แบนปกติแทนการแบนครั้งเดียว แล้วยิง event misconfig · อาการนี้แปลว่า trustProxy น่าจะผิด (ลูกค้าทุกคนดูเป็น IP ของ load balancer) หรือ server ของเราเองอยู่บน provider นั้น · ลูกค้าที่ต่อจากเน็ตบ้าน/มือถือไม่อยู่ใน range ของ cloud จึงไม่โดนบล็อก แต่ webhook จาก Google/AWS และ service ของเราเองบน Cloud Run ต้องใส่ cloud.ignorePaths หรือ ipAllowlist (Cloud NAT ให้ IP ขาออกคงที่)
googleกับgcp:gcpคือเครื่อง VM ของลูกค้า Google Cloud เท่านั้น ส่วนgoogleรวม Cloud Run, Cloud Functions และ App Engine ด้วย (เช่น2600:1900::/29ที่ไม่อยู่ในcloud.json) โดยหัก Googlebot และ crawler/fetcher ของ Google ออกเสมอ ถ้าโหลดรายการ crawler ไม่ได้จะไม่เปิดใช้googleเลย SEO จึงไม่พัง- เจ้าอื่น (Azure, Hetzner, OVH, Vultr) ใส่เองได้
cloud: { ranges: { hetzner: ['5.9.0.0/16', ...] }, providers: ['hetzner'] } - ถ้าโหลด feed ไม่ได้ (เครื่องไม่มี internet ขาออก) จะยิง event
misconfigและใช้รายการเดิมต่อ · รอโหลดเสร็จได้ด้วยawait shield.cloudReady()· เช็ค IP ด้วยshield.cloudProvider(ip) - ความเสี่ยงของ fingerprint: ถ้าคนร้ายเลียนแบบ header ของ mobile app เรา แล้วโจมตีจนโดนแบน ผู้ใช้ app ทุกคนจะโดนด้วยจนกว่าจะหมดเวลาแบน จึงเป็น opt-in
DLP กับ response ขนาดใหญ่และ streaming
| กรณี | การทำงาน |
|---|---|
| Response ปกติ ไม่เกิน dlp.maxScanBytes (512KB) รวม writeHead(), gzip/deflate/br, Fastify, Koa และ res.write() ที่แบ่งหลายครั้ง | สแกนทั้ง body |
| เกินเพดาน หรือ stream ที่ส่งนานกว่า dlp.flushMs (200ms) | ค่า default streamOverflow: 'pass' ส่งต่อทันทีและ mask PII ทีละ chunk นับใน stats().dlpUnscanned และยิง event dlp_unscanned |
| SSE, NDJSON, gRPC (dlp.streamTypes) | ส่งทันทีและ mask PII ทีละ chunk |
| อยากให้ปลอดภัยแบบเข้มงวด | dlp: { streamOverflow: 'block' } รอจนจบ response แล้วสแกนทั้งหมด ถ้าเกินเพดานตอบ 500 ไม่เหมาะกับไฟล์ใหญ่หรือ streaming |
ข้อจำกัดของ pass: ข้อมูลลับที่ถูกตัดคร่อมสอง chunk หลังเริ่มส่งแล้วจะตรวจไม่เจอ, gzip ที่เป็น live stream ไม่ถูกสแกน และหลัง flushHeaders() แทนที่ทั้ง response ไม่ได้แล้ว · ไฟล์ JavaScript จะรายงาน PII แต่ไม่ mask เพราะตัวเลขใน bundle มักผ่าน Luhn โดยบังเอิญ
Stack trace และ DB error: ซ่อนเมื่อ response เป็น 4xx/5xx ส่วน 2xx จะแค่รายงาน เพราะหน้าเอกสารหรือ comment ที่พูดถึง MongoError เป็นหน้าปกติ และการเปลี่ยนหน้าเหล่านั้นเป็น 500 จะเปิดช่องให้ comment เดียวทำให้หน้าพังทุกคน ถ้าแอปตอบ error ดิบด้วย status 200 และต้องการซ่อนด้วย ให้ตั้ง dlp: { errorsOn2xx: 'mask' }
API อื่นๆ
shield.assertTenant(record)ใช้กับ ORM — throw ถ้า record เป็นของ tenant อื่นshield.setUser(req, user)·shield.on('attack' | 'ban' | 'ratelimit' | 'slowloris' | 'overload' | 'misconfig' | 'dlp_unscanned' | 'error', fn)shield.ban(ip, ms)/unban/stats()·shield.jwt.verify(token)· IPv6 นับเป็นราย /64shield.checkSql/checkShell/checkPath/checkJs/checkMongo(...)สำหรับตรวจเองในจุดที่ไม่มี hookinit({ modules: { mysql2: require('mysql2') } })ใช้เมื่อแอป resolve driver คนละตัวกับ shieldinit({ hookEval: false })ปิด hookFunction/eval· ตอนเปิด hook อยู่evalแบบ direct จะทำงานใน global scope จึงอ่านตัวแปร local ไม่ได้ ถ้าโค้ดหรือ library ต้องใช้ ให้ปิด hook นี้init({ rateLimitStore })ส่ง store ที่ใช้ Redis เข้าไปได้ ต้อง implementincr(key, windowMs)→{ count, resetMs }ถ้า store ล่ม request ยังผ่านและยิง eventerrorinit({ inspection: { maxInputs, maxDepth, overflow } })request ที่มี input เกินเพดาน (20,000 ค่า หรือซ้อน 32 ชั้น) ตอบ 413 เพราะตรวจไม่ครบ ตั้งoverflow: 'allow'ได้ถ้ายอมรับความเสี่ยงinit({ crashGuard: false })ปิดการกันแอปล่ม · ค่า default ถ้า Shield บล็อก sink ใน async handler หรือ callback ที่ไม่ได้ catch จะตอบ 403 แล้วแอปทำงานต่อ · error อื่นยังจบ process ตามปกติของ Node · ถ้าแอปมีuncaughtExceptionlistener ของตัวเองที่สั่งprocess.exitให้ข้าม error ที่err.name === 'ShieldBlockedError'- ใช้กับ TypeScript ได้เลย (
index.d.ts)
ทดสอบ
ยิงแอปของเราเองด้วยชุดทดสอบ 141 เคส หลังติดตั้งแพ็กเกจ (รายงานบนหน้าเว็บอัปเดตเมื่อ deploy demo ใช้กับ dev/staging เท่านั้น):
npx inverz-shield-attack --target http://localhost:3000 --only sql,xss # → reports/attack-report.htmlใน repo นี้:
npm test # unit + Fastify/Koa/Express 5/ESM/MongoDB/XML + regression ของช่องโหว่ที่เคยพบ (93 tests)
npm run test:db # MySQL/MariaDB + PostgreSQL จริง (ตั้ง MYSQL_URL, PG_URL)
npm run attack # demo app เปิด/ปิด shield แล้วยิงเทียบกัน 141 เคส → reports/attack-report.html
node attack/run.js --target http://localhost:3000 --only sql,xss # ยิงแอปของเราเอง (dev/staging เท่านั้น)
demo/vulnerable-app.jsจงใจเขียนให้มีช่องโหว่ไว้สำหรับทดสอบเท่านั้น ห้าม deploy
ข้อจำกัดที่ยังเหลือ
- IDOR: ตรวจได้เฉพาะ raw SQL ที่ไม่กรอง
tenant_idบนทุกเงื่อนไข OR และการไล่ ID · ค่าใน placeholder (?,$1) มองไม่เห็นจาก SQL จึงตรวจค่าไม่ได้ และเงื่อนไขเดียวใน JOIN นับรวมทุกตารางใน scope นั้น ส่วน logic เช่น "user คนนี้แก้ invoice นี้ได้ไหม" ภายใน tenant เดียวกัน ยังต้องเช็คในโค้ดเอง (ใช้assertTenantช่วยได้) - Multi-instance: rate limit ใช้ store ที่เป็น Redis ได้ แต่การแบน IP, provider, fingerprint และ behavior ยังเก็บใน memory ของแต่ละ instance (sync เองได้ผ่าน event
banกับshield.ban()) - ตัวกันพลาดของ cloud: เว็บที่ traffic น้อยมาก คนร้ายที่ส่ง request ปกติจาก cloud มากพอ (10 ครั้งขึ้นไปและเกิน 20%) จะทำให้ provider นั้นกลับไปใช้เกณฑ์แบนปกติ 8 ครั้ง (การแบนรายตัวและ fingerprint ยังทำงาน)
- IP rotation: คนร้ายที่ใช้ residential proxy (IP บ้านคนจริง) หรือปลอม header ให้เหมือน browser จะไม่โดน cloud และ fingerprint ต้องพึ่ง rate limit, CAPTCHA หรือ Cloudflare Bot Management
- Driver ที่ไม่ได้ hook: SQL hook ครอบเฉพาะ
mysql2,mysql,pg,better-sqlite3,node:sqliteเท่านั้น · Prisma (query engine แยก process),postgres,mariadb,mssql,oracledb,sqlite3ไม่ผ่าน hook ต้องเรียกshield.checkSql()เอง · HTTP client ที่ไม่ได้ใช้http(s)/fetchของ Node (เช่นundiciโดยตรง) ได้รับการป้องกันแค่ระดับnet.connect - Signature: เป็นการจับรูปแบบ ไม่มีทางครอบคลุมทุก payload และอาจบล็อกข้อความปกติบางแบบ เช่น บทความที่พูดถึงแท็ก
<link>(ใช้exceptions) - Sink hook: เทียบ input กับสิ่งที่ไปถึง sink ถ้าแอปแปลงค่าแบบอื่นนอกจาก trim, lowercase และ decode ที่รองรับ (เช่น ตัดคำแล้วต่อใหม่) จะเทียบไม่เจอ · argument injection ตรวจเฉพาะคำสั่งแบบ string ไม่ตรวจ
spawn('curl', [input]) writeHead(): Shield ถือไว้จนถึง byte แรกheadersSentยังเป็นtrueตามปกติ แต่writeHeadซ้ำและsetHeaderหลังจากนั้นจะไม่ throwERR_HTTP_HEADERS_SENT- Worker thread: crash guard ทำงานเฉพาะ main thread · sink ที่ถูกบล็อกโดยไม่ catch ใน worker จะจบ worker นั้นตามปกติ
- SSRF หลัง proxy ภายใน: input
localhostจาก user คู่กับการเปิด connection ใหม่ไปlocalhostของแอปเอง (เช่น DB pool) ใน request เดียวกัน จะถูกมองเป็น SSRF - DDoS ระดับ network: ยังต้องพึ่ง Cloudflare หรือ Cloud Armor
- XSS: ตรวจด้วย signature เป็นด่านเสริมเท่านั้น ยังต้อง escape output และตั้ง CSP เอง
- JWKS: ตอนนี้รองรับแบบ static เท่านั้น ยังไม่ได้ดึงจาก URL อัตโนมัติ
- AI/LLM: Shield กันช่องโหว่เว็บและ sink อันตรายที่คนหรือ AI อาจยิงเข้ามา แต่ไม่ได้ตรวจ prompt injection/jailbreak หรือแทนที่ sandbox และ tool permission ของ AI agent
- SSRF: Shield resolve DNS ใหม่ทุก redirect hop แต่การป้องกัน DNS rebinding แบบเด็ดขาดยังต้องบังคับ egress allow-list/firewall ที่ระดับ network
License
MIT © 2026 Inverz Solutions Co.,Ltd.
