fase(6): fuzzing module complete

This commit is contained in:
debian
2026-03-05 09:22:55 -05:00
parent d62bd615bf
commit e746dc0497
46 changed files with 1727 additions and 35 deletions

View File

@@ -0,0 +1,66 @@
import { UseCase } from '../../../../shared/application/UseCase';
import { EventBus } from '../../../../shared/application/EventBus';
import { Result, Ok, Err } from '../../../../shared/domain/Result';
import { FuzzSession } from '../../domain/entities/FuzzSession';
import { IFuzzerEngine } from '../../domain/ports/IFuzzerEngine';
import { IState } from '../../../../core/interfaces';
export interface IFuzzSessionRepository {
save(session: FuzzSession): Promise<void>;
findById(id: string): Promise<FuzzSession | null>;
update(session: FuzzSession): Promise<void>;
}
interface RunFuzzRequest {
crawlSessionId: string;
intensity: 'low' | 'medium' | 'high';
seed: number;
state: IState;
}
interface RunFuzzResponse {
fuzzSessionId: string;
actionsGenerated: number;
}
export class RunFuzzCommand implements UseCase<RunFuzzRequest, RunFuzzResponse, string> {
constructor(
private readonly fuzzerEngine: IFuzzerEngine,
private readonly repository: IFuzzSessionRepository,
private readonly eventBus: EventBus
) {}
async execute(request: RunFuzzRequest): Promise<Result<RunFuzzResponse, string>> {
const sessionResult = FuzzSession.create({
crawlSessionId: request.crawlSessionId,
intensity: request.intensity,
seed: request.seed,
});
if (!sessionResult.ok) {
return Err(sessionResult.error);
}
const session = sessionResult.value;
await this.repository.save(session);
const actions = this.fuzzerEngine.generateFuzzActions(request.state.domSnapshot, request.state);
for (const _action of actions) {
session.incrementActions();
}
session.complete();
await this.repository.update(session);
for (const event of session.domainEvents) {
await this.eventBus.publish(event);
}
session.clearEvents();
return Ok({
fuzzSessionId: session.id.toString(),
actionsGenerated: actions.length,
});
}
}

View File

@@ -0,0 +1,31 @@
import { EventHandler } from '../../../../shared/application/EventHandler';
import { DomainEvent } from '../../../../shared/domain/DomainEvent';
import { RunFuzzCommand } from '../commands/RunFuzzCommand';
import { IAction, IState } from '../../../../core/interfaces';
/**
* Listens for action_executed events from crawling module
* and triggers fuzzing on the resulting state's DOM.
*/
export class OnActionExecuted implements EventHandler {
constructor(private readonly runFuzz: RunFuzzCommand) {}
async handle(event: DomainEvent): Promise<void> {
const payload = event.payload as {
action?: IAction;
state?: IState;
sessionId?: string;
intensity?: 'low' | 'medium' | 'high';
};
if (!payload.state || !payload.sessionId) return;
if (!payload.state.domSnapshot) return;
await this.runFuzz.execute({
crawlSessionId: payload.sessionId,
intensity: payload.intensity ?? 'low',
seed: payload.action?.seed ?? Date.now(),
state: payload.state,
});
}
}

View File

@@ -0,0 +1,34 @@
import { Entity } from '../../../../shared/domain/Entity';
import { UniqueId } from '../../../../shared/domain/UniqueId';
export interface FuzzResultProps {
sessionId: string;
stateId: string;
selector: string;
payload: string;
strategy: string;
anomalyType: string;
severity: 'low' | 'medium' | 'high' | 'critical';
description: string;
detectedAt: Date;
}
export class FuzzResult extends Entity<FuzzResultProps> {
static create(props: Omit<FuzzResultProps, 'detectedAt'>, id?: UniqueId): FuzzResult {
return new FuzzResult({ ...props, detectedAt: new Date() }, id);
}
static reconstitute(props: FuzzResultProps, id: UniqueId): FuzzResult {
return new FuzzResult(props, id);
}
get sessionId(): string { return this.props.sessionId; }
get stateId(): string { return this.props.stateId; }
get selector(): string { return this.props.selector; }
get payload(): string { return this.props.payload; }
get strategy(): string { return this.props.strategy; }
get anomalyType(): string { return this.props.anomalyType; }
get severity(): 'low' | 'medium' | 'high' | 'critical' { return this.props.severity; }
get description(): string { return this.props.description; }
get detectedAt(): Date { return this.props.detectedAt; }
}

View File

@@ -0,0 +1,131 @@
import { AggregateRoot } from '../../../../shared/domain/AggregateRoot';
import { UniqueId } from '../../../../shared/domain/UniqueId';
import { Result, Ok, Err } from '../../../../shared/domain/Result';
import { FuzzIntensity } from '../value-objects/FuzzIntensity';
import { Seed } from '../value-objects/Seed';
import { FuzzStarted } from '../events/FuzzStarted';
import { FuzzCompleted } from '../events/FuzzCompleted';
import { VulnerabilityDetected } from '../events/VulnerabilityDetected';
import { FuzzResult } from './FuzzResult';
type FuzzSessionStatus = 'running' | 'completed' | 'failed';
export interface FuzzSessionProps {
crawlSessionId: string;
intensity: FuzzIntensity;
seed: Seed;
status: FuzzSessionStatus;
actionsExecuted: number;
vulnerabilitiesFound: number;
startedAt: Date;
completedAt?: Date;
}
export interface CreateFuzzSessionRequest {
crawlSessionId: string;
intensity: 'low' | 'medium' | 'high';
seed: number;
}
export class FuzzSession extends AggregateRoot<FuzzSessionProps> {
private constructor(props: FuzzSessionProps, id?: UniqueId) {
super(props, id);
}
static reconstitute(props: FuzzSessionProps, id: UniqueId): FuzzSession {
return new FuzzSession(props, id);
}
static create(request: CreateFuzzSessionRequest): Result<FuzzSession, string> {
let intensity: FuzzIntensity;
try {
intensity = FuzzIntensity.fromString(request.intensity);
} catch (e) {
return Err((e as Error).message);
}
let seed: Seed;
try {
seed = Seed.create(request.seed);
} catch (e) {
return Err((e as Error).message);
}
const props: FuzzSessionProps = {
crawlSessionId: request.crawlSessionId,
intensity,
seed,
status: 'running',
actionsExecuted: 0,
vulnerabilitiesFound: 0,
startedAt: new Date(),
};
const session = new FuzzSession(props);
session.addDomainEvent(
new FuzzStarted(session.id.toString(), {
crawlSessionId: request.crawlSessionId,
intensity: request.intensity,
seed: request.seed,
})
);
return Ok(session);
}
get crawlSessionId(): string { return this.props.crawlSessionId; }
get intensity(): FuzzIntensity { return this.props.intensity; }
get seed(): Seed { return this.props.seed; }
get status(): FuzzSessionStatus { return this.props.status; }
get actionsExecuted(): number { return this.props.actionsExecuted; }
get vulnerabilitiesFound(): number { return this.props.vulnerabilitiesFound; }
get startedAt(): Date { return this.props.startedAt; }
get completedAt(): Date | undefined { return this.props.completedAt; }
recordVulnerability(result: FuzzResult): void {
this.props = {
...this.props,
actionsExecuted: this.props.actionsExecuted + 1,
vulnerabilitiesFound: this.props.vulnerabilitiesFound + 1,
};
this.addDomainEvent(
new VulnerabilityDetected(this.id.toString(), {
crawlSessionId: this.props.crawlSessionId,
stateId: result.stateId,
anomalyType: result.anomalyType,
severity: result.severity,
selector: result.selector,
payload: result.payload,
strategy: result.strategy,
})
);
}
incrementActions(): void {
this.props = { ...this.props, actionsExecuted: this.props.actionsExecuted + 1 };
}
complete(): void {
this.props = { ...this.props, status: 'completed', completedAt: new Date() };
this.addDomainEvent(
new FuzzCompleted(this.id.toString(), {
crawlSessionId: this.props.crawlSessionId,
actionsExecuted: this.props.actionsExecuted,
vulnerabilitiesFound: this.props.vulnerabilitiesFound,
})
);
}
fail(reason: string): void {
this.props = { ...this.props, status: 'failed', completedAt: new Date() };
this.addDomainEvent(
new FuzzCompleted(this.id.toString(), {
crawlSessionId: this.props.crawlSessionId,
actionsExecuted: this.props.actionsExecuted,
vulnerabilitiesFound: this.props.vulnerabilitiesFound,
failed: true,
reason,
})
);
}
}

View File

@@ -0,0 +1,13 @@
import { randomUUID } from 'crypto';
import { DomainEvent } from '../../../../shared/domain/DomainEvent';
export class FuzzCompleted implements DomainEvent {
readonly eventId = randomUUID();
readonly eventName = 'fuzz.completed';
readonly occurredOn = new Date();
constructor(
readonly aggregateId: string,
readonly payload: Record<string, unknown>
) {}
}

View File

@@ -0,0 +1,13 @@
import { randomUUID } from 'crypto';
import { DomainEvent } from '../../../../shared/domain/DomainEvent';
export class FuzzStarted implements DomainEvent {
readonly eventId = randomUUID();
readonly eventName = 'fuzz.started';
readonly occurredOn = new Date();
constructor(
readonly aggregateId: string,
readonly payload: Record<string, unknown>
) {}
}

View File

@@ -0,0 +1,13 @@
import { randomUUID } from 'crypto';
import { DomainEvent } from '../../../../shared/domain/DomainEvent';
export class VulnerabilityDetected implements DomainEvent {
readonly eventId = randomUUID();
readonly eventName = 'fuzz.vulnerability_detected';
readonly occurredOn = new Date();
constructor(
readonly aggregateId: string,
readonly payload: Record<string, unknown>
) {}
}

View File

@@ -0,0 +1,6 @@
import { IAction, IState } from '../../../../core/interfaces';
export interface IFuzzerEngine {
/** Generate fuzz fill actions for a DOM snapshot at a given state */
generateFuzzActions(domSnapshot: string, state: IState): IAction[];
}

View File

@@ -0,0 +1,24 @@
import { ValueObject } from '../../../../shared/domain/ValueObject';
type IntensityLevel = 'low' | 'medium' | 'high';
interface FuzzIntensityProps {
value: IntensityLevel;
}
export class FuzzIntensity extends ValueObject<FuzzIntensityProps> {
static readonly LEVELS: IntensityLevel[] = ['low', 'medium', 'high'];
static low(): FuzzIntensity { return new FuzzIntensity({ value: 'low' }); }
static medium(): FuzzIntensity { return new FuzzIntensity({ value: 'medium' }); }
static high(): FuzzIntensity { return new FuzzIntensity({ value: 'high' }); }
static fromString(s: string): FuzzIntensity {
if (!FuzzIntensity.LEVELS.includes(s as IntensityLevel)) {
throw new Error(`Invalid intensity: ${s}. Must be one of: ${FuzzIntensity.LEVELS.join(', ')}`);
}
return new FuzzIntensity({ value: s as IntensityLevel });
}
get value(): IntensityLevel { return this.props.value; }
}

View File

@@ -0,0 +1,15 @@
import { ValueObject } from '../../../../shared/domain/ValueObject';
interface FuzzPayloadProps {
value: string;
strategy: string;
}
export class FuzzPayload extends ValueObject<FuzzPayloadProps> {
static create(value: string, strategy: string): FuzzPayload {
return new FuzzPayload({ value, strategy });
}
get value(): string { return this.props.value; }
get strategy(): string { return this.props.strategy; }
}

View File

@@ -0,0 +1,26 @@
import { ValueObject } from '../../../../shared/domain/ValueObject';
type StrategyName = 'empty' | 'oversized' | 'special_chars' | 'type_mismatch' | 'boundary';
interface FuzzStrategyProps {
value: StrategyName;
}
export class FuzzStrategy extends ValueObject<FuzzStrategyProps> {
static readonly ALL: StrategyName[] = ['empty', 'oversized', 'special_chars', 'type_mismatch', 'boundary'];
static empty(): FuzzStrategy { return new FuzzStrategy({ value: 'empty' }); }
static oversized(): FuzzStrategy { return new FuzzStrategy({ value: 'oversized' }); }
static specialChars(): FuzzStrategy { return new FuzzStrategy({ value: 'special_chars' }); }
static typeMismatch(): FuzzStrategy { return new FuzzStrategy({ value: 'type_mismatch' }); }
static boundary(): FuzzStrategy { return new FuzzStrategy({ value: 'boundary' }); }
static fromString(s: string): FuzzStrategy {
if (!FuzzStrategy.ALL.includes(s as StrategyName)) {
throw new Error(`Invalid fuzz strategy: ${s}`);
}
return new FuzzStrategy({ value: s as StrategyName });
}
get value(): StrategyName { return this.props.value; }
}

View File

@@ -0,0 +1,20 @@
import { ValueObject } from '../../../../shared/domain/ValueObject';
interface SeedProps {
value: number;
}
export class Seed extends ValueObject<SeedProps> {
static create(value: number): Seed {
if (!Number.isInteger(value) || value < 0) {
throw new Error(`Seed must be a non-negative integer, got: ${value}`);
}
return new Seed({ value });
}
static fromTimestamp(): Seed {
return new Seed({ value: Date.now() });
}
get value(): number { return this.props.value; }
}

View File

@@ -0,0 +1,17 @@
// Domain
export { FuzzSession } from './domain/entities/FuzzSession';
export { FuzzResult } from './domain/entities/FuzzResult';
export { FuzzIntensity } from './domain/value-objects/FuzzIntensity';
export { FuzzStrategy } from './domain/value-objects/FuzzStrategy';
export { FuzzPayload } from './domain/value-objects/FuzzPayload';
export { Seed } from './domain/value-objects/Seed';
export type { IFuzzerEngine } from './domain/ports/IFuzzerEngine';
// Application
export { RunFuzzCommand } from './application/commands/RunFuzzCommand';
export type { IFuzzSessionRepository } from './application/commands/RunFuzzCommand';
export { OnActionExecuted } from './application/event-handlers/OnActionExecuted';
// Infrastructure
export { FuzzingEngineAdapter } from './infrastructure/adapters/FuzzingEngineAdapter';
export { createFuzzingRouter } from './infrastructure/http/FuzzingController';

View File

@@ -0,0 +1,121 @@
/**
* FuzzingEngineAdapter — implements IFuzzerEngine port using the 5 fuzzing strategies.
* Adapts the legacy FuzzingEngine logic to the hexagonal architecture.
*/
import * as crypto from 'crypto';
import { IAction, IState } from '../../../../core/interfaces';
import { IFuzzerEngine } from '../../domain/ports/IFuzzerEngine';
import { detectInputType, DetectedInputType } from './InputTypeDetector';
import { EmptyValueStrategy } from '../strategies/EmptyValueStrategy';
import { OversizedStringStrategy } from '../strategies/OversizedStringStrategy';
import { SpecialCharsStrategy } from '../strategies/SpecialCharsStrategy';
import { TypeMismatchStrategy } from '../strategies/TypeMismatchStrategy';
import { BoundaryValueStrategy } from '../strategies/BoundaryValueStrategy';
interface FormField {
selector: string;
tagName: string;
inputType?: string;
name?: string;
placeholder?: string;
ariaLabel?: string;
}
const INPUT_RE = /<(input|textarea|select)[^>]*>/gi;
const ATTR_RE = (name: string): RegExp => new RegExp(`${name}="([^"]*)"`, 'i');
function extractFields(domSnapshot: string): FormField[] {
const fields: FormField[] = [];
let match: RegExpExecArray | null;
while ((match = INPUT_RE.exec(domSnapshot)) !== null) {
const tag = match[0] ?? '';
const tagName = match[1] ?? 'input';
const idMatch = ATTR_RE('id').exec(tag);
const nameMatch = ATTR_RE('name').exec(tag);
const typeMatch = ATTR_RE('type').exec(tag);
const placeholderMatch = ATTR_RE('placeholder').exec(tag);
const ariaMatch = ATTR_RE('aria-label').exec(tag);
const selector = idMatch?.[1]
? `#${idMatch[1]}`
: nameMatch?.[1]
? `[name="${nameMatch[1]}"]`
: tagName;
fields.push({
selector,
tagName,
inputType: typeMatch?.[1],
name: nameMatch?.[1],
placeholder: placeholderMatch?.[1],
ariaLabel: ariaMatch?.[1],
});
}
return fields;
}
type FuzzingStrategy = {
name: string;
appliesTo(type: DetectedInputType): boolean;
values(type?: DetectedInputType): string[];
};
export class FuzzingEngineAdapter implements IFuzzerEngine {
private readonly intensity: 'low' | 'medium' | 'high';
private readonly seed: number;
constructor(config: { intensity: 'low' | 'medium' | 'high'; seed: number }) {
this.intensity = config.intensity;
this.seed = config.seed;
}
generateFuzzActions(domSnapshot: string, state: IState): IAction[] {
const fields = extractFields(domSnapshot);
const actions: IAction[] = [];
const now = Date.now();
const strategies = this.selectStrategies();
for (const field of fields) {
const detectedType = detectInputType({
tagName: field.tagName,
inputType: field.inputType,
name: field.name,
placeholder: field.placeholder,
ariaLabel: field.ariaLabel,
});
for (const strategy of strategies) {
if (!strategy.appliesTo(detectedType)) continue;
const values = strategy.values(detectedType);
for (const value of values) {
actions.push({
id: crypto.randomUUID(),
type: 'fill',
selector: field.selector,
value,
timestamp: now,
seed: this.seed,
stateId: state.id,
});
}
}
}
return actions;
}
private selectStrategies(): FuzzingStrategy[] {
const empty = new EmptyValueStrategy();
const typeMismatch = new TypeMismatchStrategy();
const oversized = new OversizedStringStrategy(this.intensity);
const boundary = new BoundaryValueStrategy();
const special = new SpecialCharsStrategy();
switch (this.intensity) {
case 'low': return [empty, typeMismatch];
case 'medium': return [empty, typeMismatch, oversized, boundary];
case 'high': return [empty, typeMismatch, oversized, boundary, special];
}
}
}

View File

@@ -0,0 +1,41 @@
import { DetectedInputType } from '../strategies/EmptyValueStrategy';
export type { DetectedInputType };
export function detectInputType(attrs: {
tagName?: string;
inputType?: string;
name?: string;
placeholder?: string;
ariaLabel?: string;
}): DetectedInputType {
const tag = (attrs.tagName ?? '').toLowerCase();
if (tag === 'textarea') return 'textarea';
if (tag === 'select') return 'select';
const inputType = (attrs.inputType ?? '').toLowerCase();
if (inputType === 'email') return 'email';
if (inputType === 'password') return 'password';
if (inputType === 'number') return 'number';
if (inputType === 'date') return 'date';
if (inputType === 'tel') return 'phone';
if (inputType === 'url') return 'url';
if (inputType === 'search') return 'search';
if (inputType === 'file') return 'file';
const hints = [
(attrs.name ?? '').toLowerCase(),
(attrs.placeholder ?? '').toLowerCase(),
(attrs.ariaLabel ?? '').toLowerCase(),
].join(' ');
if (/email/.test(hints)) return 'email';
if (/password|pass/.test(hints)) return 'password';
if (/phone|tel|mobile/.test(hints)) return 'phone';
if (/date|birth|dob/.test(hints)) return 'date';
if (/number|qty|quantity|age/.test(hints)) return 'number';
if (/search/.test(hints)) return 'search';
if (/url|website|link/.test(hints)) return 'url';
return 'text';
}

View File

@@ -0,0 +1,71 @@
import { Router, Request, Response } from 'express';
import { RunFuzzCommand, IFuzzSessionRepository } from '../../application/commands/RunFuzzCommand';
import { FuzzSession } from '../../domain/entities/FuzzSession';
import { IState } from '../../../../core/interfaces';
export interface FuzzingControllerDeps {
runFuzz: RunFuzzCommand;
repository: IFuzzSessionRepository;
}
export function createFuzzingRouter(deps: FuzzingControllerDeps): Router {
const router = Router();
// POST /api/fuzz/run — trigger fuzzing for a given state
router.post('/run', async (req: Request, res: Response) => {
const { crawlSessionId, intensity, seed, state } = req.body as {
crawlSessionId?: string;
intensity?: 'low' | 'medium' | 'high';
seed?: number;
state?: IState;
};
if (!crawlSessionId || !state) {
res.status(400).json({ error: 'crawlSessionId and state are required' });
return;
}
const result = await deps.runFuzz.execute({
crawlSessionId,
intensity: intensity ?? 'low',
seed: seed ?? Date.now(),
state,
});
if (!result.ok) {
res.status(422).json({ error: result.error });
return;
}
res.status(201).json(result.value);
});
// GET /api/fuzz/sessions/:id — get fuzz session
router.get('/sessions/:id', async (req: Request, res: Response) => {
const sessionId = req.params['id'] as string;
const session = await deps.repository.findById(sessionId);
if (!session) {
res.status(404).json({ error: 'Fuzz session not found' });
return;
}
res.json(toDTO(session));
});
return router;
}
function toDTO(s: FuzzSession) {
return {
id: s.id.toString(),
crawlSessionId: s.crawlSessionId,
intensity: s.intensity.value,
seed: s.seed.value,
status: s.status,
actionsExecuted: s.actionsExecuted,
vulnerabilitiesFound: s.vulnerabilitiesFound,
startedAt: s.startedAt.toISOString(),
completedAt: s.completedAt?.toISOString() ?? null,
};
}

View File

@@ -0,0 +1,17 @@
import { DetectedInputType } from './EmptyValueStrategy';
export class BoundaryValueStrategy {
readonly name = 'BoundaryValueStrategy';
appliesTo(type: DetectedInputType): boolean {
return type === 'number' || type === 'date';
}
values(type: DetectedInputType): string[] {
switch (type) {
case 'number': return ['0', '-1', '2147483647', '2147483648', '-2147483648'];
case 'date': return ['1900-01-01', '2099-12-31', '1970-01-01'];
default: return [];
}
}
}

View File

@@ -0,0 +1,15 @@
export type DetectedInputType =
| 'email' | 'password' | 'number' | 'date' | 'phone'
| 'url' | 'search' | 'text' | 'textarea' | 'select' | 'file';
export class EmptyValueStrategy {
readonly name = 'EmptyValueStrategy';
appliesTo(_type: DetectedInputType): boolean {
return true;
}
values(): string[] {
return ['', ' ', '\t'];
}
}

View File

@@ -0,0 +1,21 @@
import { DetectedInputType } from './EmptyValueStrategy';
const APPLICABLE_TYPES: DetectedInputType[] = ['text', 'email', 'password', 'textarea'];
export class OversizedStringStrategy {
readonly name = 'OversizedStringStrategy';
constructor(private readonly intensity: 'low' | 'medium' | 'high') {}
appliesTo(type: DetectedInputType): boolean {
return APPLICABLE_TYPES.includes(type);
}
values(): string[] {
switch (this.intensity) {
case 'low': return ['A'.repeat(256)];
case 'medium': return ['A'.repeat(1024)];
case 'high': return ['A'.repeat(10000) + '日本語テスト𠮷野家'];
}
}
}

View File

@@ -0,0 +1,21 @@
import { DetectedInputType } from './EmptyValueStrategy';
const APPLICABLE_TYPES: DetectedInputType[] = ['text', 'email', 'search', 'textarea'];
export class SpecialCharsStrategy {
readonly name = 'SpecialCharsStrategy';
appliesTo(type: DetectedInputType): boolean {
return APPLICABLE_TYPES.includes(type);
}
values(): string[] {
return [
"' OR 1=1 --",
'<script>alert(1)</script>',
'../../etc/passwd',
'${7*7}',
'\x00\x01\x02',
];
}
}

View File

@@ -0,0 +1,20 @@
import { DetectedInputType } from './EmptyValueStrategy';
export class TypeMismatchStrategy {
readonly name = 'TypeMismatchStrategy';
appliesTo(type: DetectedInputType): boolean {
return ['email', 'number', 'date', 'url', 'phone'].includes(type);
}
values(type: DetectedInputType): string[] {
switch (type) {
case 'email': return ['not-an-email', '12345', '@@@'];
case 'number': return ['abc', '-999999', '9.9.9', 'NaN'];
case 'date': return ['yesterday', '32/13/2025', '0000-00-00'];
case 'url': return ['javascript:alert(1)', 'not a url'];
case 'phone': return ['000', '++++', 'abcdefghij'];
default: return [];
}
}
}