Unity Shield Middleware

Security middleware agent for Express applications. Part of the Unity Sentinel & Shield security ecosystem.


Features

- IP Blocklist - O(1) Redis lookups for blocked IPs
- Rate Limiting - Sliding window rate limiting by path/method/IP
- Honeypot Detection - Catch scanners accessing trap endpoints
- JA3 Fingerprinting - Detect bots falsifying User-Agent
- Async Telemetry - Non-blocking metrics to Sentinel dashboard
- Circuit Breaker - Fail-open pattern for high availability

Installation

``bash
npm install @unityfinancialnetwork/shield-middleware
`

Quick Start

`typescript
import express from 'express';
import { createShield } from '@unityfinancialnetwork/shield-middleware';

const app = express();

async function main() {
// Initialize Shield
const shield = await createShield({
appId: 'my-api-server',
sentinelUrl: 'https://unity-sentinel-u8gbx.ondigitalocean.app/api',
apiKey: process.env.SHIELD_API_KEY!,
redisUrl: process.env.REDIS_URL!,
});

// Apply middleware (MUST be before your routes)
app.use(shield.middleware());

// Your routes
app.get('/api/users', (req, res) => {
res.json({ users: [] });
});

app.listen(3000, () => {
console.log('Server protected by Shield');
});

// Graceful shutdown
process.on('SIGTERM', async () => {
await shield.shutdown();
process.exit(0);
});
}

main();
`

Configuration

`typescript
interface ShieldConfig {
// Required
appId: string; // Unique identifier for your app
sentinelUrl: string; // Sentinel API URL
apiKey: string; // Your Shield API key
redisUrl: string; // Redis connection URL

// Optional
failOpen?: boolean; // Allow traffic if Redis/Sentinel down (default: true)
circuitBreakerThreshold?: number; // Failures before opening circuit (default: 5)
circuitBreakerResetMs?: number; // Reset timeout in ms (default: 30000)
telemetryBatchSize?: number; // Events per batch (default: 100)
telemetryFlushMs?: number; // Flush interval in ms (default: 5000)
excludePaths?: string[]; // Paths to skip (default: ['/health', '/ready', '/metrics'])
debug?: boolean; // Enable debug logging (default: false)
}
`

Environment Variables

Create a .env file in your project:

`bash


Shield Configuration

SHIELD_API_KEY=your-api-key-here
SENTINEL_URL=https://unity-sentinel-u8gbx.ondigitalocean.app/api
REDIS_URL=rediss://user:password@host:port

Optional

SHIELD_APP_ID=my-app-name
SHIELD_DEBUG=false
`

Integration Examples

$3

`javascript
const express = require('express');
const { createShield } = require('@unityfinancialnetwork/shield-middleware');

const app = express();

(async () => {
const shield = await createShield({
appId: process.env.SHIELD_APP_ID || 'express-api',
sentinelUrl: process.env.SENTINEL_URL,
apiKey: process.env.SHIELD_API_KEY,
redisUrl: process.env.REDIS_URL,
});

app.use(shield.middleware());

app.get('/', (req, res) => res.send('Protected!'));

app.listen(3000);
})();
`

$3

`typescript
// shield.module.ts
import { Module, Global, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { createShield, Shield } from '@unityfinancialnetwork/shield-middleware';

@Global()
@Module({})
export class ShieldModule implements OnModuleInit, OnModuleDestroy {
private shield: Shield;

async onModuleInit() {
this.shield = await createShield({
appId: 'nestjs-api',
sentinelUrl: process.env.SENTINEL_URL!,
apiKey: process.env.SHIELD_API_KEY!,
redisUrl: process.env.REDIS_URL!,
});
}

async onModuleDestroy() {
await this.shield.shutdown();
}

getMiddleware() {
return this.shield.middleware();
}
}

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ShieldModule } from './shield.module';

async function bootstrap() {
const app = await NestFactory.create(AppModule);

const shieldModule = app.get(ShieldModule);
app.use(shieldModule.getMiddleware());

await app.listen(3000);
}
bootstrap();
`

$3

`typescript
import Fastify from 'fastify';
import middie from '@fastify/middie';
import { createShield } from '@unityfinancialnetwork/shield-middleware';

const fastify = Fastify();

async function main() {
await fastify.register(middie);

const shield = await createShield({
appId: 'fastify-api',
sentinelUrl: process.env.SENTINEL_URL!,
apiKey: process.env.SHIELD_API_KEY!,
redisUrl: process.env.REDIS_URL!,
});

fastify.use(shield.middleware());

fastify.get('/', async () => ({ hello: 'world' }));

await fastify.listen({ port: 3000 });
}

main();
`

What Gets Protected

Once integrated, Shield automatically:

| Protection | Description |
|------------|-------------|
| Blocks malicious IPs | Checks every request against centralized blocklist |
| Enforces rate limits | Sliding window limits per path/method/IP |
| Detects honeypot access | Auto-blocks IPs accessing trap endpoints |
| Collects telemetry | Sends request metrics to Sentinel dashboard |
| JA3 fingerprinting | Detects TLS fingerprint mismatches |

Viewing Data in Sentinel Dashboard

After integration, visit your Sentinel dashboard to see:

- Dashboard - Real-time request metrics and blocked threats
- Threat Map - Geographic origin of attacks
- Alerts - Security events requiring attention
- Blocklist - Manually and automatically blocked IPs
- Honeypots - Trap endpoint hit statistics
- Logs - Detailed security event logs

API Reference

$3

Creates and initializes a Shield instance.

`typescript
const shield = await createShield({
appId: 'my-app',
sentinelUrl: 'https://sentinel.example.com/api',
apiKey: 'your-api-key',
redisUrl: 'redis://localhost:6379',
});
`

$3

Returns Express middleware function.

`typescript
app.use(shield.middleware());
`

$3

Gracefully shuts down Shield, flushing pending telemetry.

`typescript
await shield.shutdown();
`

$3

Returns health status of Shield components.

`typescript
const health = await shield.isHealthy();
// { redis: true, sentinel: true, circuitBreaker: 'CLOSED' }
`

Troubleshooting

$3

If Shield can't connect to Redis or Sentinel:

1. Fail-open behavior: Traffic is allowed (won't break your app)
2. Check network connectivity to Redis/Sentinel
3. Verify credentials in environment variables
4. Check circuit breaker status with shield.isHealthy()

$3

Enable debug logging:

`typescript
const shield = await createShield({
// ... config
debug: true,
});
`

$3

| Error | Solution |
|-------|----------|
| ECONNREFUSED to Redis | Check REDIS_URL and network access |
| 401 Unauthorized from Sentinel | Verify SHIELD_API_KEY is correct |
| Circuit breaker OPEN` | Redis/Sentinel unavailable, traffic allowed |

Support

- Dashboard: https://unity-sentinel-u8gbx.ondigitalocean.app
- API Docs: https://unity-sentinel-u8gbx.ondigitalocean.app/api/docs
- Repository: https://github.com/terrizoaguimor/sentinel-by-unity

License

MIT