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.
509 lines
18 KiB
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,
|
|
];
|
|
}
|
|
}
|