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.
314 lines
10 KiB
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;
|
|
}
|
|
}
|