@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

npm install @kya-os/agentshield

Quick Start

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

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

AgentDetector

The main class for agent detection.

constructor(config?: AgentShieldConfig)

Create a new agent detector with optional configuration.

analyze(context: RequestContext): Promise<DetectionResult>

Analyze a request context and return detection results.

updateConfig(config: Partial<AgentShieldConfig>): void

Update the detector configuration.

getConfig(): AgentShieldConfig

Get the current detector configuration.

Types

RequestContext

interface RequestContext {
  userAgent?: string;
  ip?: string;
  headers?: Record<string, string>;
  url?: string;
  method?: string;
  body?: unknown;
  timestamp?: Date;
}

DetectionResult

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

Advanced Usage

Custom Analysis

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);

Caching

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