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/CloudAbuseDetectionPolicy.php

314 lines
10 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Immutable, validated network-abuse detection policy.
*
* The policy owns the audited rule catalog and timing thresholds. Callers
* receive copies of its arrays, so a request cannot mutate the process-wide
* defaults used by later projections.
*/
final readonly class CloudAbuseDetectionPolicy
{
public const ENGINE_VERSION = 1;
public const DEFAULT_WARMUP_WINDOWS = 60;
public const DEFAULT_SUSPICIOUS_WINDOWS = 3;
public const DEFAULT_HIGH_WINDOWS = 2;
public const DEFAULT_CLEAR_WINDOWS = 5;
private const MAX_WARMUP_WINDOWS = 1440;
private const MAX_STREAK_WINDOWS = 60;
private const MAX_THRESHOLD = 1000000000;
private const DEFINITION_KEYS = [
'engine_version', 'windows', 'rules',
];
private const WINDOW_KEYS = [
'warmup', 'suspicious', 'high', 'clear',
];
private const RULE_KEYS = [
'enabled', 'direction', 'protocol', 'signals', 'high',
];
/** @var array<string,array<string,mixed>> */
private const DEFAULT_RULES = [
'outbound_tcp_syn_sweep' => [
'enabled' => true,
'direction' => 'outbound', 'protocol' => 'tcp',
'signals' => ['tcp_syn_flows' => 800,
'unique_remote_ips' => 128],
'high' => ['tcp_syn_flows' => 4000,
'unique_remote_ips' => 512],
],
'outbound_tcp_port_scan' => [
'enabled' => true,
'direction' => 'outbound', 'protocol' => 'tcp',
'signals' => ['tcp_syn_flows' => 400,
'max_remote_ports_per_remote_ip' => 48],
'high' => ['tcp_syn_flows' => 2000,
'max_remote_ports_per_remote_ip' => 256],
],
'outbound_udp_fanout' => [
'enabled' => true,
'direction' => 'outbound', 'protocol' => 'udp',
'signals' => ['udp_new_flows' => 1200,
'unique_remote_ips' => 256],
'high' => ['udp_new_flows' => 6000,
'unique_remote_ips' => 1024],
],
'inbound_tcp_syn_attack' => [
'enabled' => true,
'direction' => 'inbound', 'protocol' => 'tcp',
'signals' => ['tcp_syn_flows' => 4000,
'tcp_unreplied_flows' => 3000],
'high' => ['tcp_syn_flows' => 20000,
'tcp_unreplied_flows' => 15000],
],
'inbound_tcp_port_scan' => [
'enabled' => true,
'direction' => 'inbound', 'protocol' => 'tcp',
'signals' => ['tcp_syn_flows' => 400,
'max_local_ports_per_remote_ip' => 48],
'high' => ['tcp_syn_flows' => 2000,
'max_local_ports_per_remote_ip' => 256],
],
'inbound_udp_flood' => [
'enabled' => true,
'direction' => 'inbound', 'protocol' => 'udp',
'signals' => ['udp_active_flows' => 5000,
'udp_new_flows' => 1000],
'high' => ['udp_active_flows' => 25000,
'udp_new_flows' => 5000],
],
];
/**
* @param array<string,array<string,mixed>> $rules
*/
private function __construct(
private int $engineVersion,
private int $warmupWindows,
private int $suspiciousWindows,
private int $highWindows,
private int $clearWindows,
private array $rules
) {
}
public static function defaults(): self
{
return new self(
self::ENGINE_VERSION,
self::DEFAULT_WARMUP_WINDOWS,
self::DEFAULT_SUSPICIOUS_WINDOWS,
self::DEFAULT_HIGH_WINDOWS,
self::DEFAULT_CLEAR_WINDOWS,
self::DEFAULT_RULES
);
}
/** @param array<string,mixed> $definition */
public static function fromDefinition(array $definition): self
{
self::assertExactKeys($definition, self::DEFINITION_KEYS, 'policy');
if (($definition['engine_version'] ?? null) !== self::ENGINE_VERSION) {
throw new \InvalidArgumentException(
'Unsupported network abuse policy engine version'
);
}
$windows = $definition['windows'] ?? null;
if (!is_array($windows) || array_is_list($windows)) {
throw new \InvalidArgumentException(
'Invalid network abuse policy windows'
);
}
self::assertExactKeys($windows, self::WINDOW_KEYS, 'policy windows');
$normalizedWindows = [
'warmup' => self::positiveInteger(
$windows['warmup'] ?? null,
self::MAX_WARMUP_WINDOWS,
'warmup window'
),
'suspicious' => self::positiveInteger(
$windows['suspicious'] ?? null,
self::MAX_STREAK_WINDOWS,
'suspicious window'
),
'high' => self::positiveInteger(
$windows['high'] ?? null,
self::MAX_STREAK_WINDOWS,
'high-risk window'
),
'clear' => self::positiveInteger(
$windows['clear'] ?? null,
self::MAX_STREAK_WINDOWS,
'clear window'
),
];
$rules = $definition['rules'] ?? null;
if (!is_array($rules) || array_is_list($rules)
|| !self::hasExactKeys($rules, array_keys(self::DEFAULT_RULES))) {
throw new \InvalidArgumentException(
'Invalid network abuse policy rule catalog'
);
}
$normalizedRules = [];
foreach (self::DEFAULT_RULES as $code => $catalogRule) {
$rule = $rules[$code] ?? null;
if (!is_array($rule) || array_is_list($rule)) {
throw new \InvalidArgumentException(
'Invalid network abuse policy rule: ' . $code
);
}
self::assertExactKeys($rule, self::RULE_KEYS, 'policy rule');
if (!is_bool($rule['enabled'] ?? null)
|| ($rule['direction'] ?? null) !== $catalogRule['direction']
|| ($rule['protocol'] ?? null) !== $catalogRule['protocol']) {
throw new \InvalidArgumentException(
'Invalid network abuse policy rule identity: ' . $code
);
}
$signals = self::thresholds(
$rule['signals'] ?? null,
array_keys($catalogRule['signals']),
$code . ' suspicious'
);
$high = self::thresholds(
$rule['high'] ?? null,
array_keys($catalogRule['high']),
$code . ' high'
);
foreach ($signals as $signal => $minimum) {
if ($high[$signal] < $minimum) {
throw new \InvalidArgumentException(
'High-risk threshold is below suspicious threshold: '
. $code . '.' . $signal
);
}
}
$normalizedRules[$code] = [
'enabled' => $rule['enabled'],
'direction' => $catalogRule['direction'],
'protocol' => $catalogRule['protocol'],
'signals' => $signals,
'high' => $high,
];
}
return new self(
self::ENGINE_VERSION,
$normalizedWindows['warmup'],
$normalizedWindows['suspicious'],
$normalizedWindows['high'],
$normalizedWindows['clear'],
$normalizedRules
);
}
public function engineVersion(): int
{
return $this->engineVersion;
}
/** @return array{warmup:int,suspicious:int,high:int,clear:int} */
public function windows(): array
{
return [
'warmup' => $this->warmupWindows,
'suspicious' => $this->suspiciousWindows,
'high' => $this->highWindows,
'clear' => $this->clearWindows,
];
}
/** @return array<string,array<string,mixed>> */
public function rules(): array
{
return $this->rules;
}
/** @return array<string,mixed> */
public function definition(): array
{
return [
'engine_version' => $this->engineVersion,
'windows' => $this->windows(),
'rules' => $this->rules,
];
}
public function hash(): string
{
return hash('sha256', json_encode(
$this->definition(),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
| JSON_UNESCAPED_UNICODE
));
}
/** @param array<string,mixed> $value @param list<string> $expected */
private static function assertExactKeys(
array $value,
array $expected,
string $label
): void {
$keys = array_keys($value);
sort($keys, SORT_STRING);
$sortedExpected = $expected;
sort($sortedExpected, SORT_STRING);
if ($keys !== $sortedExpected) {
throw new \InvalidArgumentException(
'Invalid network abuse ' . $label . ' fields'
);
}
}
private static function positiveInteger(
mixed $value,
int $maximum,
string $label
): int {
if (!is_int($value) || is_bool($value)
|| $value < 1 || $value > $maximum) {
throw new \InvalidArgumentException(
'Invalid network abuse ' . $label
);
}
return $value;
}
/**
* @param list<string> $expectedSignals
* @return array<string,int>
*/
private static function thresholds(
mixed $value,
array $expectedSignals,
string $label
): array {
if (!is_array($value) || array_is_list($value)
|| !self::hasExactKeys($value, $expectedSignals)) {
throw new \InvalidArgumentException(
'Invalid network abuse thresholds: ' . $label
);
}
$thresholds = [];
foreach ($expectedSignals as $signal) {
$thresholds[$signal] = self::positiveInteger(
$value[$signal] ?? null,
self::MAX_THRESHOLD,
$label . '.' . $signal
);
}
return $thresholds;
}
/** @param array<string,mixed> $value @param list<string> $expected */
private static function hasExactKeys(array $value, array $expected): bool
{
$keys = array_keys($value);
sort($keys, SORT_STRING);
sort($expected, SORT_STRING);
return $keys === $expected;
}
}