iri-shield 1.2.0 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +183 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,74 +1,88 @@
|
|
|
1
|
-
#
|
|
1
|
+
# iri-shield
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/iri-shield)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
|
-
[](#-explainable-risk-scoring)
|
|
7
7
|
[](#-privacy-by-design)
|
|
8
8
|
|
|
9
|
-
>
|
|
9
|
+
<p align="center">
|
|
10
|
+
<img src="./img/iri-shield-home.jpg" alt="Iri Shield Logo" width="500">
|
|
11
|
+
</p>
|
|
10
12
|
|
|
11
|
-
---
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- [Architectural Philosophy](#-architectural-philosophy)
|
|
16
|
-
- [Key Features](#-key-features)
|
|
17
|
-
- [Installation](#-installation)
|
|
18
|
-
- [Quick Start](#-quick-start)
|
|
19
|
-
- [Explainable Risk Scoring](#-explainable-risk-scoring)
|
|
20
|
-
- [Multi-Signal Identity Continuity](#-multi-signal-identity-continuity)
|
|
21
|
-
- [Security Rule Engine](#-security-rule-engine)
|
|
22
|
-
- [Behavioural Anomaly & Correlation](#-behavioural-anomaly--correlation)
|
|
23
|
-
- [Privacy Controls & Fail-Safe Modes](#-privacy-controls--fail-safe-modes)
|
|
24
|
-
- [Interactive Admin Dashboard](#-interactive-admin-dashboard)
|
|
25
|
-
- [Automated Benchmarking](#-automated-benchmarking)
|
|
26
|
-
- [Full Configuration Reference](#-full-configuration-reference)
|
|
27
|
-
- [Security & Auth Utilities](#-security--auth-utilities)
|
|
28
|
-
- [Academic & Research Defense](#-academic--research-defense)
|
|
29
|
-
- [License](#-license)
|
|
14
|
+
> **Open-source API security middleware for Express.js** featuring **Explainable Risk Scoring**, **Multi-Signal Identity Continuity Analysis**, **Behavioural Anomaly Detection**, **Attack Sequence Correlation**, **Configurable Rule Engine**, **Automated PII/Secret Redaction**, and an **Interactive Real-Time Admin Dashboard**.
|
|
30
15
|
|
|
31
16
|
---
|
|
32
17
|
|
|
33
|
-
##
|
|
34
|
-
|
|
35
|
-
|
|
18
|
+
## Table of Contents
|
|
19
|
+
|
|
20
|
+
- [iri-shield](#iri-shield)
|
|
21
|
+
- [Table of Contents](#table-of-contents)
|
|
22
|
+
- [Architectural Philosophy](#architectural-philosophy)
|
|
23
|
+
- [Key Features](#key-features)
|
|
24
|
+
- [Installation](#installation)
|
|
25
|
+
- [Quick Start](#quick-start)
|
|
26
|
+
- [Explainable Risk Scoring](#explainable-risk-scoring)
|
|
27
|
+
- [Multi-Signal Identity Continuity](#multi-signal-identity-continuity)
|
|
28
|
+
- [Security Rule Engine](#security-rule-engine)
|
|
29
|
+
- [Behavioural Anomaly \& Correlation](#behavioural-anomaly--correlation)
|
|
30
|
+
- [1. Rolling Behaviour Baseline](#1-rolling-behaviour-baseline)
|
|
31
|
+
- [2. Attack Sequence Correlation](#2-attack-sequence-correlation)
|
|
32
|
+
- [Privacy Controls \& Fail-Safe Modes](#privacy-controls--fail-safe-modes)
|
|
33
|
+
- [Automated Benchmarking \& Research Evaluation](#automated-benchmarking--research-evaluation)
|
|
34
|
+
- [Comprehensive Research Evaluation Summary (v1.2.0-research)](#comprehensive-research-evaluation-summary-v120-research)
|
|
35
|
+
- [Multi-Workload Performance \& Latency Matrix](#multi-workload-performance--latency-matrix)
|
|
36
|
+
- [Interactive Admin Dashboard](#interactive-admin-dashboard)
|
|
37
|
+
- [🚀 Real-World \& Production Deployment Guide](#-real-world--production-deployment-guide)
|
|
38
|
+
- [1. Disabling Testing Mode for Real Traffic](#1-disabling-testing-mode-for-real-traffic)
|
|
39
|
+
- [2. Reverse Proxy \& Real Client IP (`trustProxy`)](#2-reverse-proxy--real-client-ip-trustproxy)
|
|
40
|
+
- [3. Securing Admin Dashboard Credentials](#3-securing-admin-dashboard-credentials)
|
|
41
|
+
- [4. Production Ready Configuration Example](#4-production-ready-configuration-example)
|
|
42
|
+
- [Full Configuration Reference](#full-configuration-reference)
|
|
43
|
+
- [Security \& Auth Utilities](#security--auth-utilities)
|
|
44
|
+
- [Academic \& Research Defense](#academic--research-defense)
|
|
45
|
+
- [Theoretical Foundation](#theoretical-foundation)
|
|
46
|
+
- [License](#license)
|
|
36
47
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
---
|
|
49
|
+
## Architectural Philosophy
|
|
50
|
+
|
|
51
|
+
`iri-shield` follows a **transparent, multi-layered security architecture**.
|
|
52
|
+
Instead of relying on a single detection mechanism, it combines identity signals, configurable security rules, behavioural analysis, attack correlation, explainable risk scoring, and automated mitigation.
|
|
53
|
+
|
|
54
|
+
```mermaid
|
|
55
|
+
flowchart TD
|
|
56
|
+
A[Incoming HTTP Request] --> B[Base Security<br/>Helmet • CORS • Fail-Safe Policy]
|
|
57
|
+
B --> C[Identity Continuity<br/>IP • Session • Client Hints • Drift Analysis]
|
|
58
|
+
C --> D[Security Rule Engine<br/>SQLi • XSS • SSTI • Path Traversal • Custom Rules]
|
|
59
|
+
D --> E[Behavioural Analysis<br/>Rolling Baseline • Anomaly Detection]
|
|
60
|
+
E --> F[Attack Sequence Correlation<br/>Multi-Step Attack Detection]
|
|
61
|
+
F --> G[Explainable Risk Scoring<br/>Risk Score • Confidence • Breakdown]
|
|
62
|
+
G --> H[Automated Mitigation<br/>Rate Limit • Temporary/Permanent Block]
|
|
63
|
+
H --> I[Secure Response & Redaction<br/>PII • Secrets • Sensitive Logs]
|
|
50
64
|
```
|
|
51
65
|
|
|
52
66
|
---
|
|
53
67
|
|
|
54
|
-
##
|
|
68
|
+
## Key Features
|
|
55
69
|
|
|
56
70
|
| Capability | Description |
|
|
57
71
|
| :--- | :--- |
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
|
72
|
+
| **Explainable Risk Scoring** | Provides a transparent, auditable breakdown table (`+30 SQLi`, `+20 Sensitive Endpoint`, `+15 Identity Drift`) with a mathematical **Confidence Score (0-100%)**. |
|
|
73
|
+
| **Multi-Signal Profiling** | Evaluates **Identity Continuity** using IP address, session tokens, Client Hints (`sec-ch-ua`, `sec-ch-ua-platform`), user-agents, accept headers, and device context to detect evasion attempts without violating user privacy. |
|
|
74
|
+
| **Configurable Rule Engine** | Individually toggle built-in threat detection rules or declare flexible **Custom Rules** (by endpoint, method, IP prefix, user-agent regex, or body fields). |
|
|
75
|
+
| **Behavioural Baselining** | Continuously learns normal per-endpoint request rates (RPM) and flags statistical anomalies (`Behaviour deviation: 92%`). |
|
|
62
76
|
| **🔗 Attack Sequence Correlation** | Evaluates ordered request chains to detect advanced multi-step campaigns (e.g., *Failed Auth ×3 → User Enumeration → Admin Access*). |
|
|
63
|
-
|
|
|
64
|
-
|
|
|
77
|
+
| **Privacy by Design** | Built-in SHA-256 IP hashing for persistent storage and automatic FIFO retention purging (`retentionDays: 30`). |
|
|
78
|
+
| ** Fail-Safe Policies** | Choose between `fail-open` (resilience first) and `fail-closed` (strict containment) on internal subsystem failures. |
|
|
65
79
|
| ** Built-in Benchmark Suite** | Automated performance comparison against baseline unshielded servers (`npm run benchmark`) measuring throughput, latency percentiles (p50/p95/p99), and defense efficacy. |
|
|
66
|
-
|
|
|
67
|
-
|
|
|
80
|
+
| **Light-Theme Dashboard** | Enterprise management interface for real-time monitoring, reactive IP block/unblock, active alerts, security event forensics, and live configuration updates. |
|
|
81
|
+
| **Deep PII/Secret Redaction** | Deep redaction for passwords, API keys, bearer tokens, emails, phone numbers, SSNs, Aadhaar numbers, and credit cards across responses and log storage. |
|
|
68
82
|
|
|
69
83
|
---
|
|
70
84
|
|
|
71
|
-
##
|
|
85
|
+
## Installation
|
|
72
86
|
|
|
73
87
|
```bash
|
|
74
88
|
npm install iri-shield
|
|
@@ -78,7 +92,7 @@ npm install iri-shield
|
|
|
78
92
|
|
|
79
93
|
---
|
|
80
94
|
|
|
81
|
-
##
|
|
95
|
+
## Quick Start
|
|
82
96
|
|
|
83
97
|
```js
|
|
84
98
|
const express = require('express');
|
|
@@ -126,7 +140,7 @@ app.listen(3000, () => {
|
|
|
126
140
|
|
|
127
141
|
---
|
|
128
142
|
|
|
129
|
-
##
|
|
143
|
+
## Explainable Risk Scoring
|
|
130
144
|
|
|
131
145
|
Every intercepted security event produces a transparent **Score Breakdown**:
|
|
132
146
|
|
|
@@ -148,7 +162,7 @@ In the **Admin Dashboard**, expanding any Security Event displays this structure
|
|
|
148
162
|
|
|
149
163
|
---
|
|
150
164
|
|
|
151
|
-
##
|
|
165
|
+
## Multi-Signal Identity Continuity
|
|
152
166
|
|
|
153
167
|
Rather than claiming "guaranteed unique identification" (which is technically invalid across modern NATs and VPNs), `iri-shield` evaluates **Identity Continuity**:
|
|
154
168
|
|
|
@@ -170,7 +184,7 @@ Action: Risk Score Penalty (+15 pts) applied to request
|
|
|
170
184
|
|
|
171
185
|
---
|
|
172
186
|
|
|
173
|
-
##
|
|
187
|
+
## Security Rule Engine
|
|
174
188
|
|
|
175
189
|
Toggle built-in detection modules or supply flexible custom rules:
|
|
176
190
|
|
|
@@ -216,7 +230,7 @@ const shield = createShield({
|
|
|
216
230
|
|
|
217
231
|
---
|
|
218
232
|
|
|
219
|
-
##
|
|
233
|
+
## Behavioural Anomaly & Correlation
|
|
220
234
|
|
|
221
235
|
### 1. Rolling Behaviour Baseline
|
|
222
236
|
Maintains a 5-minute rolling request rate (RPM) profile per IP and endpoint. Sudden traffic spikes (>3× baseline) trigger a proportional anomaly score penalty:
|
|
@@ -237,7 +251,7 @@ Detects multi-step attack patterns across request sequences:
|
|
|
237
251
|
|
|
238
252
|
---
|
|
239
253
|
|
|
240
|
-
##
|
|
254
|
+
## Privacy Controls & Fail-Safe Modes
|
|
241
255
|
|
|
242
256
|
```js
|
|
243
257
|
const shield = createShield({
|
|
@@ -255,7 +269,7 @@ const shield = createShield({
|
|
|
255
269
|
|
|
256
270
|
---
|
|
257
271
|
|
|
258
|
-
##
|
|
272
|
+
## Automated Benchmarking & Research Evaluation
|
|
259
273
|
|
|
260
274
|
`iri-shield` includes a built-in automated evaluation suite to benchmark performance, threat detection efficacy, false positives, identity continuity, and data redaction against baseline Express.js:
|
|
261
275
|
|
|
@@ -285,10 +299,10 @@ npm run redaction:evaluate # 500-sample recursive PII masking evaluation
|
|
|
285
299
|
### Multi-Workload Performance & Latency Matrix
|
|
286
300
|
|
|
287
301
|
| Workload Configuration | Baseline Req/s | Shield Req/s | Throughput Impact | Base Latency (Avg) | Shield Latency (Avg) | Overhead (Δ) | Shield p95 | Shield p99 | Host CPU (Base vs Shield) | Cores Utilized (Base vs Shield) |
|
|
288
|
-
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
|
289
|
-
| **300 req @ c=5**
|
|
302
|
+
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
|
303
|
+
| **300 req @ c=5** | 1,904 req/s | 997 req/s | -47.6% | 2.97 ms | 4.96 ms | **+1.99 ms** | 7.80 ms | 9.77 ms | 17.6% vs 13.6% | 1.41 vs 1.09 cores |
|
|
290
304
|
| **300 req @ c=15** | 2,404 req/s | 706 req/s | -70.6% | 6.28 ms | 21.49 ms | **+15.21 ms** | 34.24 ms | 35.73 ms | 12.8% vs 14.7% | 1.02 vs 1.17 cores |
|
|
291
|
-
| **500 req @ c=5**
|
|
305
|
+
| **500 req @ c=5** | 2,669 req/s | 630 req/s | -76.4% | 1.86 ms | 7.92 ms | **+6.06 ms** | 12.16 ms | 16.58 ms | 14.9% vs 13.1% | 1.19 vs 1.05 cores |
|
|
292
306
|
| **500 req @ c=15** | 3,097 req/s | 730 req/s | -76.4% | 4.79 ms | 20.44 ms | **+15.65 ms** | 29.80 ms | 33.06 ms | 15.2% vs 14.9% | 1.21 vs 1.19 cores |
|
|
293
307
|
|
|
294
308
|
> **CPU Metric Definitions:**
|
|
@@ -299,12 +313,12 @@ JSON and CSV benchmark artifacts are automatically recorded in `results/`, `fina
|
|
|
299
313
|
|
|
300
314
|
---
|
|
301
315
|
|
|
302
|
-
##
|
|
316
|
+
## Interactive Admin Dashboard
|
|
303
317
|
|
|
304
318
|
Access the real-time security dashboard at `/iri-shield`:
|
|
305
319
|
|
|
306
320
|
- **Overview Panel**: Live requests, mitigated threats, latency gauges, threat distribution donut charts, and top endpoint statistics.
|
|
307
|
-
- **Alerts
|
|
321
|
+
- **Alerts**: Active suspicious client queue with one-click **Block IP** and **Dismiss** actions.
|
|
308
322
|
- **Security Events**: Filterable by risk level (`critical`, `high`, `medium`, `low`) with expandable **Risk Breakdown Tables**, **Confidence Badges**, and **Correlation Banners**.
|
|
309
323
|
- **Client Identity**: Identity continuity records, platform breakdown, IP rotation count, and anomaly histories.
|
|
310
324
|
- **Blocked IPs**: Full persistent blocklist management with instant **Unblock** and manual block creation modal.
|
|
@@ -312,15 +326,117 @@ Access the real-time security dashboard at `/iri-shield`:
|
|
|
312
326
|
|
|
313
327
|
---
|
|
314
328
|
|
|
315
|
-
##
|
|
329
|
+
## 🚀 Real-World & Production Deployment Guide
|
|
330
|
+
|
|
331
|
+
`iri-shield` is built to protect production Express.js APIs against real-world threats. When moving from local testing or dataset benchmarks to production, follow these steps:
|
|
332
|
+
|
|
333
|
+
### 1. Disabling Testing Mode for Real Traffic
|
|
334
|
+
By default in `iri-shield`, **testing mode is already disabled** (`enabled: false`). However, if you enabled it during local simulation or integration testing, ensure it is set to `false` or removed in production.
|
|
335
|
+
|
|
336
|
+
> [!WARNING]
|
|
337
|
+
> When `testing.enabled: true`, clients can spoof their IP, User-Agent, and Session ID via custom headers (`x-iri-test-ip`, `x-iri-test-user-agent`, etc.) for benchmark replay. **Never enable testing mode in production environments!**
|
|
338
|
+
|
|
339
|
+
```js
|
|
340
|
+
const shield = createShield({
|
|
341
|
+
appName: 'my-production-api',
|
|
342
|
+
// Ensure testing mode is off (or simply omit the testing property)
|
|
343
|
+
testing: {
|
|
344
|
+
enabled: false,
|
|
345
|
+
allowClientOverrides: false
|
|
346
|
+
},
|
|
347
|
+
// ...
|
|
348
|
+
});
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
### 2. Reverse Proxy & Real Client IP (`trustProxy`)
|
|
352
|
+
If your application runs behind a reverse proxy, load balancer, or CDN (such as **Nginx**, **Cloudflare**, **AWS ALB**, or **Heroku**):
|
|
353
|
+
- Set `trustProxy: true` (or express `app.set('trust-proxy', 1)`) so `iri-shield` reads real client IPs from `CF-Connecting-IP`, `X-Forwarded-For`, or `X-Real-IP`.
|
|
354
|
+
|
|
355
|
+
```js
|
|
356
|
+
const app = express();
|
|
357
|
+
app.set('trust proxy', true);
|
|
358
|
+
|
|
359
|
+
const shield = createShield({
|
|
360
|
+
appName: 'my-production-api',
|
|
361
|
+
trustProxy: true,
|
|
362
|
+
// ...
|
|
363
|
+
});
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### 3. Securing Admin Dashboard Credentials
|
|
367
|
+
Never hardcode default credentials in production code. Load admin username and password from environment variables:
|
|
368
|
+
|
|
369
|
+
```js
|
|
370
|
+
dashboard: {
|
|
371
|
+
enabled: true,
|
|
372
|
+
path: '/iri-shield',
|
|
373
|
+
username: process.env.SHIELD_ADMIN_USER || 'admin',
|
|
374
|
+
password: process.env.SHIELD_ADMIN_PASSWORD, // enforce strong secret via .env
|
|
375
|
+
refreshMs: 60 * 1000
|
|
376
|
+
}
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### 4. Production Ready Configuration Example
|
|
380
|
+
|
|
381
|
+
```js
|
|
382
|
+
const express = require('express');
|
|
383
|
+
const { createShield } = require('iri-shield');
|
|
384
|
+
|
|
385
|
+
const app = express();
|
|
386
|
+
const isProd = process.env.NODE_ENV === 'production';
|
|
387
|
+
|
|
388
|
+
if (isProd) {
|
|
389
|
+
app.set('trust proxy', true);
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
const shield = createShield({
|
|
393
|
+
appName: process.env.APP_NAME || 'my-api',
|
|
394
|
+
security: isProd ? 'high' : 'medium', // 'low' | 'medium' | 'high'
|
|
395
|
+
trustProxy: isProd,
|
|
396
|
+
failureMode: 'fail-open', // resilient: won't bring down app on errors
|
|
397
|
+
|
|
398
|
+
// Testing mode — automatically OFF in production
|
|
399
|
+
testing: {
|
|
400
|
+
enabled: !isProd,
|
|
401
|
+
allowClientOverrides: !isProd
|
|
402
|
+
},
|
|
403
|
+
|
|
404
|
+
// Persistent storage for production blocks and analytics
|
|
405
|
+
storage: {
|
|
406
|
+
mode: process.env.STORAGE_MODE || 'sqlite', // 'sqlite' or 'mongodb'
|
|
407
|
+
sqliteFile: process.env.SQLITE_PATH || './data/iri-shield.sqlite'
|
|
408
|
+
},
|
|
409
|
+
|
|
410
|
+
// Secure Dashboard
|
|
411
|
+
dashboard: {
|
|
412
|
+
enabled: true,
|
|
413
|
+
path: '/iri-shield',
|
|
414
|
+
username: process.env.SHIELD_ADMIN_USER || 'admin',
|
|
415
|
+
password: process.env.SHIELD_ADMIN_PASSWORD || 'ChangeThisSecret123!'
|
|
416
|
+
}
|
|
417
|
+
});
|
|
418
|
+
|
|
419
|
+
app.use(shield.middleware);
|
|
420
|
+
app.use('/iri-shield', shield.dashboard);
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
## Full Configuration Reference
|
|
316
426
|
|
|
317
427
|
```js
|
|
318
428
|
const shield = createShield({
|
|
319
429
|
appName: 'iri-shield',
|
|
320
430
|
security: 'medium', // 'low' | 'medium' | 'high'
|
|
321
|
-
trustProxy: false,
|
|
431
|
+
trustProxy: false, // Set true if behind Cloudflare, Nginx, or AWS ALB
|
|
322
432
|
failureMode: 'fail-open', // 'fail-open' | 'fail-closed'
|
|
323
433
|
|
|
434
|
+
// Testing Mode (False by default — enables header/body overrides for testing)
|
|
435
|
+
testing: {
|
|
436
|
+
enabled: false, // Keep FALSE in production
|
|
437
|
+
allowClientOverrides: false
|
|
438
|
+
},
|
|
439
|
+
|
|
324
440
|
// HTTP Security Headers & CORS
|
|
325
441
|
helmet: {
|
|
326
442
|
enabled: true,
|
|
@@ -416,7 +532,7 @@ const shield = createShield({
|
|
|
416
532
|
|
|
417
533
|
---
|
|
418
534
|
|
|
419
|
-
##
|
|
535
|
+
## Security & Auth Utilities
|
|
420
536
|
|
|
421
537
|
`iri-shield` ships with built-in cryptographic security utilities:
|
|
422
538
|
|
|
@@ -442,7 +558,7 @@ const isValid = await comparePassword('input-password', hashed);
|
|
|
442
558
|
|
|
443
559
|
---
|
|
444
560
|
|
|
445
|
-
##
|
|
561
|
+
## Academic & Research Defense
|
|
446
562
|
|
|
447
563
|
When presenting or publishing research using `iri-shield`:
|
|
448
564
|
|
|
@@ -454,6 +570,6 @@ When presenting or publishing research using `iri-shield`:
|
|
|
454
570
|
|
|
455
571
|
---
|
|
456
572
|
|
|
457
|
-
##
|
|
573
|
+
## License
|
|
458
574
|
|
|
459
|
-
|
|
575
|
+
MIT License © [ansari-in](https://github.com/ansari-in/iri-shield/blob/main/LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "iri-shield",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.2",
|
|
4
4
|
"description": "Enterprise Express.js security middleware — explainable risk scoring, multi-signal identity profiling, behavioural anomaly detection, attack correlation, sensitive-data redaction, and dashboard monitoring.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"iri-shield",
|