iri-shield 1.2.0 → 1.2.1
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 +73 -64
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,74 +1,83 @@
|
|
|
1
|
-
#
|
|
1
|
+
# iri-shield
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/iri-shield)
|
|
4
|
-
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
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
|
+
> **Enterprise-grade 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
|
+
- [Full Configuration Reference](#full-configuration-reference)
|
|
38
|
+
- [Security \& Auth Utilities](#security--auth-utilities)
|
|
39
|
+
- [Academic \& Research Defense](#academic--research-defense)
|
|
40
|
+
- [Theoretical Foundation](#theoretical-foundation)
|
|
41
|
+
- [License](#license)
|
|
36
42
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
43
|
+
---
|
|
44
|
+
## Architectural Philosophy
|
|
45
|
+
|
|
46
|
+
`iri-shield` follows a **transparent, multi-layered security architecture**.
|
|
47
|
+
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.
|
|
48
|
+
|
|
49
|
+
```mermaid
|
|
50
|
+
flowchart TD
|
|
51
|
+
A[Incoming HTTP Request] --> B[Base Security<br/>Helmet • CORS • Fail-Safe Policy]
|
|
52
|
+
B --> C[Identity Continuity<br/>IP • Session • Client Hints • Drift Analysis]
|
|
53
|
+
C --> D[Security Rule Engine<br/>SQLi • XSS • SSTI • Path Traversal • Custom Rules]
|
|
54
|
+
D --> E[Behavioural Analysis<br/>Rolling Baseline • Anomaly Detection]
|
|
55
|
+
E --> F[Attack Sequence Correlation<br/>Multi-Step Attack Detection]
|
|
56
|
+
F --> G[Explainable Risk Scoring<br/>Risk Score • Confidence • Breakdown]
|
|
57
|
+
G --> H[Automated Mitigation<br/>Rate Limit • Temporary/Permanent Block]
|
|
58
|
+
H --> I[Secure Response & Redaction<br/>PII • Secrets • Sensitive Logs]
|
|
50
59
|
```
|
|
51
60
|
|
|
52
61
|
---
|
|
53
62
|
|
|
54
|
-
##
|
|
63
|
+
## Key Features
|
|
55
64
|
|
|
56
65
|
| Capability | Description |
|
|
57
66
|
| :--- | :--- |
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
|
67
|
+
| **Explainable Risk Scoring** | Provides a transparent, auditable breakdown table (`+30 SQLi`, `+20 Sensitive Endpoint`, `+15 Identity Drift`) with a mathematical **Confidence Score (0-100%)**. |
|
|
68
|
+
| **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. |
|
|
69
|
+
| **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). |
|
|
70
|
+
| **Behavioural Baselining** | Continuously learns normal per-endpoint request rates (RPM) and flags statistical anomalies (`Behaviour deviation: 92%`). |
|
|
62
71
|
| **🔗 Attack Sequence Correlation** | Evaluates ordered request chains to detect advanced multi-step campaigns (e.g., *Failed Auth ×3 → User Enumeration → Admin Access*). |
|
|
63
|
-
|
|
|
64
|
-
|
|
|
72
|
+
| **Privacy by Design** | Built-in SHA-256 IP hashing for persistent storage and automatic FIFO retention purging (`retentionDays: 30`). |
|
|
73
|
+
| ** Fail-Safe Policies** | Choose between `fail-open` (resilience first) and `fail-closed` (strict containment) on internal subsystem failures. |
|
|
65
74
|
| ** 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
|
-
|
|
|
75
|
+
| **Light-Theme Dashboard** | Enterprise management interface for real-time monitoring, reactive IP block/unblock, active alerts, security event forensics, and live configuration updates. |
|
|
76
|
+
| **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
77
|
|
|
69
78
|
---
|
|
70
79
|
|
|
71
|
-
##
|
|
80
|
+
## Installation
|
|
72
81
|
|
|
73
82
|
```bash
|
|
74
83
|
npm install iri-shield
|
|
@@ -78,7 +87,7 @@ npm install iri-shield
|
|
|
78
87
|
|
|
79
88
|
---
|
|
80
89
|
|
|
81
|
-
##
|
|
90
|
+
## Quick Start
|
|
82
91
|
|
|
83
92
|
```js
|
|
84
93
|
const express = require('express');
|
|
@@ -126,7 +135,7 @@ app.listen(3000, () => {
|
|
|
126
135
|
|
|
127
136
|
---
|
|
128
137
|
|
|
129
|
-
##
|
|
138
|
+
## Explainable Risk Scoring
|
|
130
139
|
|
|
131
140
|
Every intercepted security event produces a transparent **Score Breakdown**:
|
|
132
141
|
|
|
@@ -148,7 +157,7 @@ In the **Admin Dashboard**, expanding any Security Event displays this structure
|
|
|
148
157
|
|
|
149
158
|
---
|
|
150
159
|
|
|
151
|
-
##
|
|
160
|
+
## Multi-Signal Identity Continuity
|
|
152
161
|
|
|
153
162
|
Rather than claiming "guaranteed unique identification" (which is technically invalid across modern NATs and VPNs), `iri-shield` evaluates **Identity Continuity**:
|
|
154
163
|
|
|
@@ -170,7 +179,7 @@ Action: Risk Score Penalty (+15 pts) applied to request
|
|
|
170
179
|
|
|
171
180
|
---
|
|
172
181
|
|
|
173
|
-
##
|
|
182
|
+
## Security Rule Engine
|
|
174
183
|
|
|
175
184
|
Toggle built-in detection modules or supply flexible custom rules:
|
|
176
185
|
|
|
@@ -216,7 +225,7 @@ const shield = createShield({
|
|
|
216
225
|
|
|
217
226
|
---
|
|
218
227
|
|
|
219
|
-
##
|
|
228
|
+
## Behavioural Anomaly & Correlation
|
|
220
229
|
|
|
221
230
|
### 1. Rolling Behaviour Baseline
|
|
222
231
|
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 +246,7 @@ Detects multi-step attack patterns across request sequences:
|
|
|
237
246
|
|
|
238
247
|
---
|
|
239
248
|
|
|
240
|
-
##
|
|
249
|
+
## Privacy Controls & Fail-Safe Modes
|
|
241
250
|
|
|
242
251
|
```js
|
|
243
252
|
const shield = createShield({
|
|
@@ -255,7 +264,7 @@ const shield = createShield({
|
|
|
255
264
|
|
|
256
265
|
---
|
|
257
266
|
|
|
258
|
-
##
|
|
267
|
+
## Automated Benchmarking & Research Evaluation
|
|
259
268
|
|
|
260
269
|
`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
270
|
|
|
@@ -285,10 +294,10 @@ npm run redaction:evaluate # 500-sample recursive PII masking evaluation
|
|
|
285
294
|
### Multi-Workload Performance & Latency Matrix
|
|
286
295
|
|
|
287
296
|
| 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**
|
|
297
|
+
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
|
298
|
+
| **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
299
|
| **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**
|
|
300
|
+
| **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
301
|
| **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
302
|
|
|
294
303
|
> **CPU Metric Definitions:**
|
|
@@ -299,12 +308,12 @@ JSON and CSV benchmark artifacts are automatically recorded in `results/`, `fina
|
|
|
299
308
|
|
|
300
309
|
---
|
|
301
310
|
|
|
302
|
-
##
|
|
311
|
+
## Interactive Admin Dashboard
|
|
303
312
|
|
|
304
313
|
Access the real-time security dashboard at `/iri-shield`:
|
|
305
314
|
|
|
306
315
|
- **Overview Panel**: Live requests, mitigated threats, latency gauges, threat distribution donut charts, and top endpoint statistics.
|
|
307
|
-
- **Alerts
|
|
316
|
+
- **Alerts**: Active suspicious client queue with one-click **Block IP** and **Dismiss** actions.
|
|
308
317
|
- **Security Events**: Filterable by risk level (`critical`, `high`, `medium`, `low`) with expandable **Risk Breakdown Tables**, **Confidence Badges**, and **Correlation Banners**.
|
|
309
318
|
- **Client Identity**: Identity continuity records, platform breakdown, IP rotation count, and anomaly histories.
|
|
310
319
|
- **Blocked IPs**: Full persistent blocklist management with instant **Unblock** and manual block creation modal.
|
|
@@ -312,7 +321,7 @@ Access the real-time security dashboard at `/iri-shield`:
|
|
|
312
321
|
|
|
313
322
|
---
|
|
314
323
|
|
|
315
|
-
##
|
|
324
|
+
## Full Configuration Reference
|
|
316
325
|
|
|
317
326
|
```js
|
|
318
327
|
const shield = createShield({
|
|
@@ -416,7 +425,7 @@ const shield = createShield({
|
|
|
416
425
|
|
|
417
426
|
---
|
|
418
427
|
|
|
419
|
-
##
|
|
428
|
+
## Security & Auth Utilities
|
|
420
429
|
|
|
421
430
|
`iri-shield` ships with built-in cryptographic security utilities:
|
|
422
431
|
|
|
@@ -442,7 +451,7 @@ const isValid = await comparePassword('input-password', hashed);
|
|
|
442
451
|
|
|
443
452
|
---
|
|
444
453
|
|
|
445
|
-
##
|
|
454
|
+
## Academic & Research Defense
|
|
446
455
|
|
|
447
456
|
When presenting or publishing research using `iri-shield`:
|
|
448
457
|
|
|
@@ -454,6 +463,6 @@ When presenting or publishing research using `iri-shield`:
|
|
|
454
463
|
|
|
455
464
|
---
|
|
456
465
|
|
|
457
|
-
##
|
|
466
|
+
## License
|
|
458
467
|
|
|
459
|
-
|
|
468
|
+
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.1",
|
|
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",
|