@kya-os/agentshield

The core AgentShield library providing AI agent detection and analysis capabilities.

Features

- 🤖 Pattern Matching: Detect AI agents by analyzing user agents, headers, and request patterns
- 🧠 Behavioral Analysis: Identify non-human behavior patterns in request timing and frequency
- 🔍 Network Analysis: Analyze IP addresses and network characteristics
- ⚡ High Performance: Optimized for production use with built-in caching
- 🔧 Configurable: Flexible configuration options for different use cases
- 📊 Confidence Scoring: Get confidence scores for detection results

Installation

``bash
npm install @kya-os/agentshield
`

Quick Start

`javascript
import { AgentDetector } from '@kya-os/agentshield';

const detector = new AgentDetector({
confidenceThreshold: 0.7,
enableCaching: true,
});

async function analyzeRequest(request) {
const context = {
userAgent: request.headers['user-agent'],
ip: request.ip,
headers: request.headers,
url: request.url,
method: request.method,
};

const result = await detector.analyze(context);

if (result.isAgent) {
console.log(Agent detected with ${result.confidence} confidence);
console.log('Reasons:', result.reasons);
}

return result;
}
`

Configuration

`javascript
const config = {
// Enable/disable detection methods
enablePatternMatching: true,
enableBehaviorAnalysis: true,
enableNetworkAnalysis: true,

// Confidence threshold (0.0 - 1.0)
confidenceThreshold: 0.7,

// Caching options
enableCaching: true,
cacheTimeout: 300000, // 5 minutes

// Custom detection rules
customRules: ['custom-bot-*', 'my-crawler'],
};

const detector = new AgentDetector(config);
`

API Reference

$3

The main class for agent detection.

#### constructor(config?: AgentShieldConfig)

Create a new agent detector with optional configuration.

#### analyze(context: RequestContext): Promise

Analyze a request context and return detection results.

#### updateConfig(config: Partial): void

Update the detector configuration.

#### getConfig(): AgentShieldConfig

Get the current detector configuration.

$3

#### RequestContext

`typescript
interface RequestContext {
userAgent?: string;
ip?: string;
headers?: Record;
url?: string;
method?: string;
body?: unknown;
timestamp?: Date;
}
`

#### DetectionResult

`typescript
interface DetectionResult {
isAgent: boolean;
confidence: number; // 0.0 - 1.0
confidenceLevel: 'low' | 'medium' | 'high';
reasons: string[];
metadata?: Record;
timestamp: Date;
}
`

Advanced Usage

$3

`javascript
import { PatternAnalyzer, BehaviorAnalyzer } from '@kya-os/agentshield';

const patternAnalyzer = new PatternAnalyzer();
const behaviorAnalyzer = new BehaviorAnalyzer();

// Analyze specific aspects
const patternResult = patternAnalyzer.analyze(context);
const behaviorResult = behaviorAnalyzer.analyze(context);
`

$3

`javascript
import { SimpleCache } from '@kya-os/agentshield';

const cache = new SimpleCache(300000); // 5 minutes TTL

// Manual cache operations
cache.set('key', 'value', 60000); // 1 minute TTL
const value = cache.get('key');
cache.cleanup(); // Remove expired entries
``

Performance

The core library is optimized for high-throughput applications:

- Memory efficient: Minimal memory footprint
- Fast analysis: Sub-millisecond detection for most requests
- Caching: Built-in result caching to avoid repeated analysis
- No external dependencies: Only uses Zod for validation

License

MIT OR Apache-2.0