You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/app/Services/Cloud/CloudAbuseDetector.php

509 lines
18 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Pure, observe-only network-abuse classifier.
*
* It consumes only the allowlisted aggregate Agent contract. It never owns
* firewall, lifecycle, billing or network mutations. Incomplete samples do
* not advance warm-up, suspicious streaks or clear streaks.
*/
final class CloudAbuseDetector
{
public const RULE_VERSION = CloudAbuseDetectionPolicy::ENGINE_VERSION;
public const WARMUP_WINDOWS =
CloudAbuseDetectionPolicy::DEFAULT_WARMUP_WINDOWS;
public const SUSPICIOUS_WINDOWS =
CloudAbuseDetectionPolicy::DEFAULT_SUSPICIOUS_WINDOWS;
public const HIGH_WINDOWS =
CloudAbuseDetectionPolicy::DEFAULT_HIGH_WINDOWS;
public const CLEAR_WINDOWS =
CloudAbuseDetectionPolicy::DEFAULT_CLEAR_WINDOWS;
/** @return array<string,mixed> */
public static function initialBaseline(
?CloudAbuseDetectionPolicy $policy = null
): array
{
$policy ??= CloudAbuseDetectionPolicy::defaults();
return [
'version' => $policy->engineVersion(),
'sample_count' => 0,
'last_bucket_start' => null,
'last_interface' => null,
'stats' => [],
'rules' => [],
];
}
/**
* Reset statistical history while preserving the minimum state required
* for already-open findings to earn a verified clear transition later.
*
* @param list<array<string,mixed>> $openFindings
* @return array<string,mixed>
*/
public static function resetBaseline(
array $openFindings = [],
?CloudAbuseDetectionPolicy $policy = null
): array
{
$policy ??= CloudAbuseDetectionPolicy::defaults();
$rules = $policy->rules();
$baseline = self::initialBaseline($policy);
foreach ($openFindings as $finding) {
$rule = (string) ($finding['rule_code'] ?? '');
$family = (string) ($finding['ip_family'] ?? '');
$severity = (string) ($finding['severity'] ?? '');
if (!isset($rules[$rule])
|| ($rules[$rule]['enabled'] ?? false) !== true
|| !in_array($family, ['ipv4', 'ipv6'], true)
|| !in_array($severity, ['suspicious', 'high'], true)
|| (string) ($finding['direction'] ?? '')
!== $rules[$rule]['direction']) {
continue;
}
$key = $family . ':' . $rule;
$existing = $baseline['rules'][$key] ?? null;
if (is_array($existing)
&& ($existing['severity'] ?? '') === 'high') {
continue;
}
$baseline['rules'][$key] = [
'active' => true,
'severity' => $severity,
'suspicious_streak' => 0,
'high_streak' => 0,
'clear_streak' => 0,
'transition' => 'continued',
];
}
return $baseline;
}
/**
* Reset statistical history after a known collection gap while retaining
* only validated active rule state from the prior durable baseline.
*
* @param array<string,mixed> $previous
* @return array<string,mixed>
*/
public static function resetBaselineFromPrevious(
array $previous,
?CloudAbuseDetectionPolicy $policy = null
): array
{
$policy ??= CloudAbuseDetectionPolicy::defaults();
$rules = $policy->rules();
$findings = [];
foreach (($previous['rules'] ?? []) as $key => $state) {
if (!is_string($key) || !is_array($state)
|| ($state['active'] ?? false) !== true) {
continue;
}
$parts = explode(':', $key, 2);
if (count($parts) !== 2) {
continue;
}
[$family, $rule] = $parts;
if (!isset($rules[$rule])
|| ($rules[$rule]['enabled'] ?? false) !== true) {
continue;
}
$findings[] = [
'rule_code' => $rule,
'direction' => $rules[$rule]['direction'],
'ip_family' => $family,
'severity' => $state['severity'] ?? '',
];
}
return self::resetBaseline($findings, $policy);
}
/**
* @param array<string,mixed> $sample Canonical allowlisted observation
* @param null|array<string,mixed> $baseline Previous compact baseline
* @return array{baseline:array<string,mixed>,evaluation:array<string,mixed>}
*/
public static function evaluate(
array $sample,
?array $baseline,
?CloudAbuseDetectionPolicy $policy = null
): array
{
$policy ??= CloudAbuseDetectionPolicy::defaults();
$windows = $policy->windows();
$rules = $policy->rules();
self::assertSample($sample);
$baseline = self::normalizeBaseline($baseline, $policy);
$bucketStart = (int) $sample['bucket_start'];
// The Agent contract may attach informational flags such as
// packet_accounting_unavailable to an otherwise complete tuple/state
// observation. Completeness has already been strictly validated at
// the transport boundary and remains the single detector gate.
$complete = $sample['complete'] === true;
$lastBucket = $baseline['last_bucket_start'];
if (is_int($lastBucket) && $bucketStart <= $lastBucket) {
return [
'baseline' => $baseline,
'evaluation' => self::collectionAnomaly(
$bucketStart,
'out_of_order_sample'
),
];
}
if (!$complete) {
return [
'baseline' => $baseline,
'evaluation' => self::collectionAnomaly(
$bucketStart,
'incomplete_sample'
),
];
}
$metrics = self::flattenMetrics((array) $sample['metrics']);
$rates = self::interfaceRates(
$baseline['last_interface'],
(array) $sample['metrics']['interface']
);
$ready = (int) $baseline['sample_count'] + 1
>= $windows['warmup'];
$findings = [];
$directions = [];
$severityRank = 0;
$latestRule = '';
foreach (['ipv4', 'ipv6'] as $family) {
foreach ($rules as $ruleCode => $rule) {
if (($rule['enabled'] ?? false) !== true) {
continue;
}
$ruleKey = $family . ':' . $ruleCode;
$scope = $family . '.' . $rule['direction'] . '.';
$values = [];
foreach (array_keys($rule['signals']) as $signal) {
$values[$signal] = $metrics[$scope . $signal] ?? 0;
}
$high = $ready && self::thresholdsMet(
$values,
$rule['high']
);
$suspicious = $ready && !$high
&& self::thresholdsMet($values, $rule['signals'])
&& self::historicallyUnusual(
$baseline['stats'],
$scope,
$values,
$rule['signals']
);
$state = self::advanceRuleState(
$baseline['rules'][$ruleKey] ?? null,
$suspicious,
$high,
$ready,
$windows
);
$baseline['rules'][$ruleKey] = $state;
if (!$state['active'] && $state['transition'] !== 'resolved') {
continue;
}
$severity = (string) $state['severity'];
$rank = $severity === 'high' ? 2 : 1;
if ($state['active']) {
$directions[(string) $rule['direction']] = true;
if ($rank > $severityRank) {
$severityRank = $rank;
$latestRule = $ruleCode;
}
}
$findings[] = [
'rule_code' => $ruleCode,
'rule_version' => $policy->engineVersion(),
'direction' => $rule['direction'],
'ip_family' => $family,
'severity' => $severity,
'active' => $state['active'],
'transition' => $state['transition'],
'consecutive_windows' => $state['active']
? max($state['suspicious_streak'],
$state['high_streak'])
: $state['clear_streak'],
'evidence' => $values,
];
}
}
foreach ($metrics as $name => $value) {
$baseline['stats'][$name] = self::updateStat(
$baseline['stats'][$name] ?? null,
$value
);
}
$baseline['sample_count'] = (int) $baseline['sample_count'] + 1;
$baseline['last_bucket_start'] = $bucketStart;
$baseline['last_interface'] = $sample['metrics']['interface'];
$direction = count($directions) === 2 ? 'both'
: (array_key_first($directions) ?? 'none');
$risk = !$ready ? 'observing'
: ($severityRank === 2 ? 'high_risk'
: ($severityRank === 1 ? 'suspicious' : 'normal'));
return [
'baseline' => $baseline,
'evaluation' => [
'bucket_start' => $bucketStart,
'collection_state' => 'healthy',
'risk_state' => $risk,
'direction' => $direction,
'latest_rule_code' => $latestRule,
'latest_severity' => $severityRank === 2 ? 'high'
: ($severityRank === 1 ? 'suspicious' : 'none'),
'sample_count' => $baseline['sample_count'],
'warmup_remaining' => max(
0,
$windows['warmup'] - $baseline['sample_count']
),
'rates' => $rates,
'findings' => $findings,
],
];
}
/** @param array<string,mixed> $sample */
private static function assertSample(array $sample): void
{
if (!isset($sample['bucket_start'], $sample['complete'],
$sample['quality_flags'], $sample['metrics'])
|| !is_int($sample['bucket_start'])
|| $sample['bucket_start'] < 1
|| $sample['bucket_start'] % 60 !== 0
|| !is_bool($sample['complete'])
|| !is_array($sample['quality_flags'])
|| !is_array($sample['metrics'])
|| !isset($sample['metrics']['interface'])
|| !is_array($sample['metrics']['interface'])) {
throw new \InvalidArgumentException(
'Invalid canonical network observation sample'
);
}
}
/** @return array<string,mixed> */
private static function normalizeBaseline(
?array $baseline,
CloudAbuseDetectionPolicy $policy
): array
{
if ($baseline === null) {
return self::initialBaseline($policy);
}
if (($baseline['version'] ?? null) !== $policy->engineVersion()
|| !is_int($baseline['sample_count'] ?? null)
|| $baseline['sample_count'] < 0
|| !is_array($baseline['stats'] ?? null)
|| !is_array($baseline['rules'] ?? null)) {
throw new \InvalidArgumentException(
'Invalid network abuse baseline'
);
}
$baseline['last_bucket_start'] ??= null;
$baseline['last_interface'] ??= null;
return $baseline;
}
/** @param array<string,mixed> $metrics @return array<string,int> */
private static function flattenMetrics(array $metrics): array
{
$result = [];
foreach (['ipv4', 'ipv6'] as $family) {
$familyMetrics = $metrics[$family] ?? null;
foreach (['inbound', 'outbound'] as $direction) {
$summary = is_array($familyMetrics)
&& is_array($familyMetrics[$direction] ?? null)
? $familyMetrics[$direction] : [];
foreach ($summary as $name => $value) {
if (!is_string($name) || !is_int($value) || $value < 0) {
throw new \InvalidArgumentException(
'Invalid canonical flow summary'
);
}
$result[$family . '.' . $direction . '.' . $name]
= $value;
}
}
}
return $result;
}
/**
* @param array<string,int> $values
* @param array<string,int> $thresholds
*/
private static function thresholdsMet(
array $values,
array $thresholds
): bool {
foreach ($thresholds as $signal => $minimum) {
if (($values[$signal] ?? 0) < $minimum) {
return false;
}
}
return true;
}
/**
* Fixed floors prevent low-volume noise. A warmed instance must also be
* materially above its own mean, except the separately defined high floor.
*
* @param array<string,mixed> $stats
* @param array<string,int> $values
* @param array<string,int> $thresholds
*/
private static function historicallyUnusual(
array $stats,
string $scope,
array $values,
array $thresholds
): bool {
foreach ($thresholds as $signal => $minimum) {
$stat = $stats[$scope . $signal] ?? null;
if (!is_array($stat) || (int) ($stat['count'] ?? 0) < 30) {
continue;
}
$mean = max(0.0, (float) ($stat['mean'] ?? 0.0));
if (($values[$signal] ?? 0) < max($minimum, $mean * 4.0)) {
return false;
}
}
return true;
}
/** @return array<string,mixed> */
private static function advanceRuleState(
mixed $previous,
bool $suspicious,
bool $high,
bool $ready,
array $windows
): array {
$state = is_array($previous) ? $previous : [];
$wasActive = ($state['active'] ?? false) === true;
$priorSeverity = in_array(
$state['severity'] ?? '',
['suspicious', 'high'],
true
) ? (string) $state['severity'] : 'suspicious';
$suspiciousStreak = max(0, (int) ($state['suspicious_streak'] ?? 0));
$highStreak = max(0, (int) ($state['high_streak'] ?? 0));
$clearStreak = max(0, (int) ($state['clear_streak'] ?? 0));
if (!$ready) {
$suspiciousStreak = $highStreak = $clearStreak = 0;
} elseif ($high) {
++$suspiciousStreak;
++$highStreak;
$clearStreak = 0;
} elseif ($suspicious) {
++$suspiciousStreak;
$highStreak = 0;
$clearStreak = 0;
} else {
$suspiciousStreak = $highStreak = 0;
++$clearStreak;
}
$active = $wasActive;
$severity = $priorSeverity;
if ($highStreak >= $windows['high']) {
$active = true;
$severity = 'high';
} elseif ($suspiciousStreak >= $windows['suspicious']) {
$active = true;
$severity = 'suspicious';
} elseif ($wasActive && $clearStreak >= $windows['clear']) {
$active = false;
}
$transition = !$wasActive && $active ? 'opened'
: ($wasActive && !$active ? 'resolved'
: ($active ? 'continued' : 'none'));
return [
'active' => $active,
'severity' => $severity,
'suspicious_streak' => $suspiciousStreak,
'high_streak' => $highStreak,
'clear_streak' => $clearStreak,
'transition' => $transition,
];
}
/** @return array{count:int,mean:float,m2:float} */
private static function updateStat(mixed $previous, int $value): array
{
$count = is_array($previous) ? max(0,
(int) ($previous['count'] ?? 0)) : 0;
$mean = is_array($previous) ? (float) ($previous['mean'] ?? 0.0)
: 0.0;
$m2 = is_array($previous) ? max(0.0,
(float) ($previous['m2'] ?? 0.0)) : 0.0;
++$count;
$delta = $value - $mean;
$mean += $delta / $count;
$m2 += $delta * ($value - $mean);
return ['count' => $count, 'mean' => $mean, 'm2' => $m2];
}
/** @param null|array<string,int> $previous @param array<string,int> $current */
private static function interfaceRates(
?array $previous,
array $current
): array {
$rates = ['rx_bps' => null, 'tx_bps' => null,
'rx_pps' => null, 'tx_pps' => null];
if ($previous === null) {
return $rates;
}
foreach ([
'rx_bytes' => 'rx_bps', 'tx_bytes' => 'tx_bps',
'rx_packets' => 'rx_pps', 'tx_packets' => 'tx_pps',
] as $counter => $rate) {
if (!is_int($previous[$counter] ?? null)
|| !is_int($current[$counter] ?? null)
|| $current[$counter] < $previous[$counter]) {
continue;
}
$delta = $current[$counter] - $previous[$counter];
if (($counter === 'rx_bytes' || $counter === 'tx_bytes')
&& $delta > intdiv(PHP_INT_MAX, 8)) {
continue;
}
$rates[$rate] = $counter === 'rx_bytes'
|| $counter === 'tx_bytes'
? intdiv($delta * 8, 60) : intdiv($delta, 60);
}
return $rates;
}
/** @return array<string,mixed> */
private static function collectionAnomaly(
int $bucketStart,
string $reason
): array {
return [
'bucket_start' => $bucketStart,
'collection_state' => 'degraded',
'risk_state' => 'observing',
'direction' => 'none',
'latest_rule_code' => '',
'latest_severity' => 'none',
'sample_count' => null,
'warmup_remaining' => null,
'rates' => ['rx_bps' => null, 'tx_bps' => null,
'rx_pps' => null, 'tx_pps' => null],
'findings' => [],
'reason' => $reason,
];
}
}