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

760 lines
26 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Owns the compact, instance-centric network-abuse state transition.
*
* The caller must already hold the logical instance row inside a main
* database transaction. This module never stores transport UUIDs, Agent
* window identities or placement hashes: one accepted minute updates the
* instance ledger, its current UTC-day aggregate and sparse transitions.
*/
final class CloudNetworkAbuseLedger
{
private const QUALITY_BITS = [
'clock_regression' => 1 << 0,
'cold_start' => 1 << 1,
'conntrack_unavailable' => 1 << 2,
'counter_reset' => 1 << 3,
'flow_limit_reached' => 1 << 4,
'incomplete' => 1 << 5,
'interface_unavailable' => 1 << 6,
'local_port_cardinality_saturated' => 1 << 7,
'mapping_changed' => 1 << 8,
'overflow' => 1 << 9,
'packet_accounting_unavailable' => 1 << 10,
'relation_cardinality_saturated' => 1 << 11,
'remote_ip_cardinality_saturated' => 1 << 12,
'remote_port_cardinality_saturated' => 1 << 13,
'sampling_gap' => 1 << 14,
'panel_ring_gap' => 1 << 15,
];
/**
* Apply one canonical minute. The surrounding transaction also advances
* the host cursor, so either every durable effect commits or none does.
*
* @param array<string,mixed> $sample
* @return array{state:string,transitions:int}
*/
public function apply(
object $database,
int $instanceId,
array $sample,
CloudAbusePolicySnapshot $snapshot,
int $now
): array {
if ($instanceId < 1 || $now < 1) {
throw new \InvalidArgumentException(
'Network abuse ledger identity is invalid'
);
}
$bucketStart = $sample['bucket_start'] ?? null;
if (!is_int($bucketStart) || $bucketStart < 1
|| $bucketStart % 60 !== 0) {
throw new \InvalidArgumentException(
'Network abuse ledger bucket is invalid'
);
}
$row = $database->table('cloud_network_instance_ledger')
->where('instance_id', $instanceId)->lockForUpdate()->first();
if ($row !== null && $row->last_bucket_start !== null
&& (int) $row->last_bucket_start >= $bucketStart) {
return ['state' => 'ignored', 'transitions' => 0];
}
$policyChanged = $row !== null
&& (int) $row->policy_revision !== $snapshot->revision;
$baseline = $row === null
? CloudAbuseDetector::initialBaseline($snapshot->policy)
: self::decodeObject(
(string) $row->detector_state_json,
'detector state'
);
if ($policyChanged) {
$baseline = self::rebaseBaseline(
$baseline,
$snapshot->policy
);
}
$quality = self::qualityFlags($sample['quality_flags'] ?? null);
if (in_array('panel_ring_gap', $quality, true)) {
$baseline = CloudAbuseDetector::resetBaselineFromPrevious(
$baseline,
$snapshot->policy
);
}
$detected = CloudAbuseDetector::evaluate(
$sample,
$baseline,
$snapshot->policy
);
$baseline = $detected['baseline'];
$evaluation = $detected['evaluation'];
$complete = ($sample['complete'] ?? null) === true;
if (!$complete) {
// Never derive the next rate across an unobserved minute.
$baseline['last_interface'] = null;
}
$transitions = 0;
if ($policyChanged) {
$transitions += $this->retireReplacedPolicyFindings(
$database,
$instanceId,
$snapshot->revision,
$bucketStart,
$now
);
}
[$dayStart, $day] = $this->advanceDay(
$database,
$instanceId,
$row,
$sample,
$evaluation,
$quality,
$bucketStart,
$complete,
$now
);
$healthy = ($evaluation['collection_state'] ?? null) === 'healthy';
$riskState = $healthy
? (string) $evaluation['risk_state']
: ($policyChanged ? 'observing'
: (string) ($row->risk_state ?? 'observing'));
$direction = $healthy
? (string) $evaluation['direction']
: ($policyChanged ? 'none'
: (string) ($row->latest_direction ?? 'none'));
$ruleCode = $healthy
? (string) $evaluation['latest_rule_code']
: ($policyChanged ? ''
: (string) ($row->latest_rule_code ?? ''));
$severity = $healthy
? (string) $evaluation['latest_severity']
: ($policyChanged ? 'none'
: (string) ($row->latest_severity ?? 'none'));
$latest = [
'rates' => $evaluation['rates'] ?? [],
'sample_count' => $evaluation['sample_count'] ?? null,
'warmup_remaining' => $evaluation['warmup_remaining'] ?? null,
'quality_flags' => $quality,
'metrics' => $sample['metrics'] ?? [],
];
$values = [
'policy_revision' => $snapshot->revision,
'risk_state' => $riskState,
'collection_state' => $healthy ? 'healthy' : 'degraded',
'latest_direction' => $direction,
'latest_rule_code' => $ruleCode,
'latest_severity' => $severity,
'detector_state_json' => self::json($baseline),
'latest_metrics_json' => self::json($latest),
'current_day_start' => $dayStart,
'current_day_json' => self::json($day),
'last_bucket_start' => $bucketStart,
'last_sample_at' => $bucketStart + 60,
'last_evaluated_at' => $healthy
? $now : ($policyChanged
? null : ($row->last_evaluated_at ?? null)),
'updated_at' => $now,
];
if ($row === null) {
$database->table('cloud_network_instance_ledger')->insert(
['instance_id' => $instanceId, 'created_at' => $now]
+ $values
);
} else {
$updated = $database->table('cloud_network_instance_ledger')
->where('instance_id', $instanceId)
->where(function ($query) use ($row): void {
if ($row->last_bucket_start === null) {
$query->whereNull('last_bucket_start');
} else {
$query->where(
'last_bucket_start',
(int) $row->last_bucket_start
);
}
})->update($values);
if ($updated !== 1) {
throw new \RuntimeException(
'Network abuse ledger compare-and-swap failed'
);
}
}
if ($healthy) {
$transitions += $this->applyFindings(
$database,
$instanceId,
$snapshot->revision,
(array) ($evaluation['findings'] ?? []),
$bucketStart,
$now
);
}
return ['state' => 'applied', 'transitions' => $transitions];
}
/**
* @param array<string,mixed> $sample
* @param array<string,mixed> $evaluation
* @param list<string> $quality
* @return array{int,array<string,int>}
*/
private function advanceDay(
object $database,
int $instanceId,
?object $row,
array $sample,
array $evaluation,
array $quality,
int $bucketStart,
bool $complete,
int $now
): array {
$dayStart = intdiv($bucketStart, 86400) * 86400;
if ($row === null) {
$day = self::emptyDay();
} else {
$previousDayStart = (int) $row->current_day_start;
$day = self::decodeDay((string) $row->current_day_json);
if ($previousDayStart !== $dayStart) {
if ($previousDayStart > $dayStart) {
throw new \RuntimeException(
'Network abuse daily ledger moved backwards'
);
}
$this->flushDay(
$database,
$instanceId,
$previousDayStart,
$day,
$now
);
$day = self::emptyDay();
}
}
return [
$dayStart,
self::accumulateDay(
$day,
$sample,
$evaluation,
$quality,
$bucketStart,
$complete
),
];
}
/** @param array<string,int> $day */
private function flushDay(
object $database,
int $instanceId,
int $dayStart,
array $day,
int $now
): void {
if (($day['sample_count'] ?? 0) < 1) {
return;
}
$values = $day + [
'created_at' => $now,
'updated_at' => $now,
];
$existing = $database->table('cloud_network_daily_summaries')
->where('instance_id', $instanceId)
->where('day_start', $dayStart)->lockForUpdate()->first();
if ($existing === null) {
$database->table('cloud_network_daily_summaries')->insert(
['instance_id' => $instanceId, 'day_start' => $dayStart]
+ $values
);
return;
}
unset($values['created_at']);
$database->table('cloud_network_daily_summaries')
->where('instance_id', $instanceId)
->where('day_start', $dayStart)->update($values);
}
/**
* @param array<string,int> $day
* @param array<string,mixed> $sample
* @param array<string,mixed> $evaluation
* @param list<string> $quality
* @return array<string,int>
*/
private static function accumulateDay(
array $day,
array $sample,
array $evaluation,
array $quality,
int $bucketStart,
bool $complete
): array {
++$day['sample_count'];
$day['complete_count'] += $complete ? 1 : 0;
$day['quality_mask'] |= self::qualityMask($quality);
$day['first_sample_at'] = $day['first_sample_at'] === 0
? $bucketStart : min($day['first_sample_at'], $bucketStart);
$day['last_sample_at'] = max(
$day['last_sample_at'],
$bucketStart
);
if (!$complete) {
return $day;
}
$rates = is_array($evaluation['rates'] ?? null)
? $evaluation['rates'] : [];
foreach (['rx_bps', 'tx_bps', 'rx_pps', 'tx_pps'] as $name) {
$rate = $rates[$name] ?? null;
if ($rate !== null && (!is_int($rate) || $rate < 0)) {
throw new \RuntimeException(
'Network abuse daily rate is invalid'
);
}
$day[$name . '_peak'] = max(
$day[$name . '_peak'],
$rate ?? 0
);
}
$flows = self::flowSummary($sample['metrics'] ?? null);
foreach ($flows as $name => $value) {
$day[$name . '_peak'] = max($day[$name . '_peak'], $value);
}
return $day;
}
/** @return array<string,int> */
private static function emptyDay(): array
{
return [
'sample_count' => 0,
'complete_count' => 0,
'quality_mask' => 0,
'rx_bps_peak' => 0,
'tx_bps_peak' => 0,
'rx_pps_peak' => 0,
'tx_pps_peak' => 0,
'tcp_active_peak' => 0,
'tcp_new_peak' => 0,
'tcp_syn_peak' => 0,
'tcp_unreplied_peak' => 0,
'udp_active_peak' => 0,
'udp_new_peak' => 0,
'peer_ip_peak' => 0,
'peer_port_peak' => 0,
'first_sample_at' => 0,
'last_sample_at' => 0,
];
}
/** @return array<string,int> */
private static function decodeDay(string $json): array
{
$value = self::decodeObject($json, 'current-day aggregate');
$empty = self::emptyDay();
if (array_keys($value) !== array_keys($empty)) {
throw new \RuntimeException(
'Network abuse current-day aggregate fields are invalid'
);
}
foreach ($value as $key => $item) {
if (!is_int($item) || $item < 0) {
throw new \RuntimeException(
'Network abuse current-day aggregate is invalid: ' . $key
);
}
}
return $value;
}
/** @return array<string,int> */
private static function flowSummary(mixed $metrics): array
{
if (!is_array($metrics)) {
throw new \RuntimeException(
'Network abuse daily metrics are invalid'
);
}
$result = [
'tcp_active' => 0,
'tcp_new' => 0,
'tcp_syn' => 0,
'tcp_unreplied' => 0,
'udp_active' => 0,
'udp_new' => 0,
'peer_ip' => 0,
'peer_port' => 0,
];
$mapping = [
'tcp_active_flows' => 'tcp_active',
'tcp_new_flows' => 'tcp_new',
'tcp_syn_flows' => 'tcp_syn',
'tcp_unreplied_flows' => 'tcp_unreplied',
'udp_active_flows' => 'udp_active',
'udp_new_flows' => 'udp_new',
'unique_remote_ips' => 'peer_ip',
'unique_remote_ports' => 'peer_port',
];
foreach (['ipv4', 'ipv6'] as $family) {
$familyMetrics = $metrics[$family] ?? null;
if ($familyMetrics === null) {
continue;
}
if (!is_array($familyMetrics)) {
throw new \RuntimeException(
'Network abuse daily address-family metrics are invalid'
);
}
foreach (['inbound', 'outbound'] as $direction) {
$flow = $familyMetrics[$direction] ?? null;
if (!is_array($flow)) {
throw new \RuntimeException(
'Network abuse daily flow metrics are invalid'
);
}
foreach ($mapping as $source => $target) {
$value = $flow[$source] ?? null;
if (!is_int($value) || $value < 0) {
throw new \RuntimeException(
'Network abuse daily flow counter is invalid'
);
}
$result[$target] = self::add(
$result[$target],
$value
);
}
}
}
return $result;
}
/**
* @param list<array<string,mixed>> $findings
*/
private function applyFindings(
object $database,
int $instanceId,
int $policyRevision,
array $findings,
int $bucketStart,
int $now
): int {
$transitions = 0;
foreach ($findings as $finding) {
$query = $database->table('cloud_network_findings')
->where('instance_id', $instanceId)
->where('policy_revision', $policyRevision)
->where('rule_code', (string) $finding['rule_code'])
->where('direction', (string) $finding['direction'])
->where('ip_family', (string) $finding['ip_family']);
$row = $query->lockForUpdate()->first();
if (($finding['active'] ?? false) === true) {
$opened = $row === null
|| (string) $row->state === 'resolved';
$escalated = $row !== null
&& (string) $row->state === 'open'
&& (string) $row->severity === 'suspicious'
&& (string) $finding['severity'] === 'high';
$generation = $row === null ? 1
: (int) $row->occurrence_generation
+ ($opened ? 1 : 0);
$revision = $row === null ? 1
: (int) $row->transition_revision
+ (($opened || $escalated) ? 1 : 0);
$values = [
'policy_revision' => $policyRevision,
'severity' => (string) $finding['severity'],
'state' => 'open',
'first_seen_at' => $opened
? $bucketStart : (int) $row->first_seen_at,
'last_seen_at' => $bucketStart,
'consecutive_windows' => max(
1,
(int) $finding['consecutive_windows']
),
'occurrence_generation' => $generation,
'transition_revision' => $revision,
'evidence_json' => self::json(
(array) ($finding['evidence'] ?? [])
),
'resolved_at' => null,
'resolution_reason' => '',
'updated_at' => $now,
];
if ($row === null) {
$findingId = (int) $database
->table('cloud_network_findings')->insertGetId([
'instance_id' => $instanceId,
'rule_code' => (string) $finding['rule_code'],
'direction' => (string) $finding['direction'],
'ip_family' => (string) $finding['ip_family'],
'created_at' => $now,
] + $values);
} else {
$findingId = (int) $row->id;
$updated = $database->table('cloud_network_findings')
->where('id', $findingId)
->where(
'transition_revision',
(int) $row->transition_revision
)->update($values);
if ($updated !== 1) {
throw new \RuntimeException(
'Network abuse finding compare-and-swap failed'
);
}
}
if ($opened || $escalated) {
$this->recordEvent(
$database,
$findingId,
$revision,
$opened ? 'opened' : 'escalated',
$opened ? 'none' : 'suspicious',
(string) $finding['severity'],
(array) ($finding['evidence'] ?? []),
'',
$bucketStart,
$now
);
++$transitions;
}
continue;
}
if (($finding['transition'] ?? '') !== 'resolved'
|| $row === null || (string) $row->state !== 'open') {
continue;
}
$revision = (int) $row->transition_revision + 1;
$updated = $database->table('cloud_network_findings')
->where('id', (int) $row->id)
->where('state', 'open')
->where(
'transition_revision',
(int) $row->transition_revision
)->update([
'state' => 'resolved',
'resolved_at' => $bucketStart,
'resolution_reason' => 'evidence_clear',
'transition_revision' => $revision,
'updated_at' => $now,
]);
if ($updated !== 1) {
throw new \RuntimeException(
'Network abuse finding resolution failed'
);
}
$this->recordEvent(
$database,
(int) $row->id,
$revision,
'resolved',
(string) $row->severity,
'none',
(array) ($finding['evidence'] ?? []),
'evidence_clear',
$bucketStart,
$now
);
++$transitions;
}
return $transitions;
}
private function retireReplacedPolicyFindings(
object $database,
int $instanceId,
int $policyRevision,
int $bucketStart,
int $now
): int {
$rows = $database->table('cloud_network_findings')
->where('instance_id', $instanceId)
->where('policy_revision', '<>', $policyRevision)
->where('state', 'open')->orderBy('id')
->lockForUpdate()->get();
$transitions = 0;
foreach ($rows as $row) {
$resolvedAt = max($bucketStart, (int) $row->last_seen_at);
$revision = (int) $row->transition_revision + 1;
$updated = $database->table('cloud_network_findings')
->where('id', (int) $row->id)
->where('state', 'open')
->where(
'transition_revision',
(int) $row->transition_revision
)->update([
'state' => 'resolved',
'resolved_at' => $resolvedAt,
'resolution_reason' => 'policy_replaced',
'transition_revision' => $revision,
'updated_at' => $now,
]);
if ($updated !== 1) {
throw new \RuntimeException(
'Network abuse policy replacement resolution failed'
);
}
$this->recordEvent(
$database,
(int) $row->id,
$revision,
'resolved',
(string) $row->severity,
'none',
self::decodeObject(
(string) $row->evidence_json,
'finding evidence'
),
'policy_replaced',
$resolvedAt,
$now
);
++$transitions;
}
return $transitions;
}
/** @param array<string,mixed> $evidence */
private function recordEvent(
object $database,
int $findingId,
int $revision,
string $type,
string $fromSeverity,
string $toSeverity,
array $evidence,
string $resolutionReason,
int $occurredAt,
int $now
): void {
$inserted = $database->table('cloud_network_alert_events')
->insertOrIgnore([
'finding_id' => $findingId,
'transition_revision' => $revision,
'transition_type' => $type,
'from_severity' => $fromSeverity,
'to_severity' => $toSeverity,
'evidence_json' => self::json($evidence),
'resolution_reason' => $resolutionReason,
'occurred_at' => $occurredAt,
'created_at' => $now,
]);
if ($inserted !== 1) {
throw new \RuntimeException(
'Network abuse alert transition identity conflict'
);
}
}
/**
* A policy change keeps long-lived statistical history but resets all
* threshold streaks because they were earned under another revision.
*
* @param array<string,mixed> $previous
* @return array<string,mixed>
*/
private static function rebaseBaseline(
array $previous,
CloudAbuseDetectionPolicy $policy
): array {
$baseline = CloudAbuseDetector::initialBaseline($policy);
$baseline['sample_count'] = max(
0,
(int) ($previous['sample_count'] ?? 0)
);
$baseline['last_bucket_start'] =
is_int($previous['last_bucket_start'] ?? null)
? $previous['last_bucket_start'] : null;
$baseline['last_interface'] =
is_array($previous['last_interface'] ?? null)
? $previous['last_interface'] : null;
$baseline['stats'] = is_array($previous['stats'] ?? null)
? $previous['stats'] : [];
return $baseline;
}
/** @return list<string> */
private static function qualityFlags(mixed $value): array
{
if (!is_array($value) || !array_is_list($value)) {
throw new \RuntimeException(
'Network abuse quality flags are invalid'
);
}
$flags = [];
foreach ($value as $flag) {
if (!is_string($flag) || !isset(self::QUALITY_BITS[$flag])) {
throw new \RuntimeException(
'Network abuse quality flag is invalid'
);
}
$flags[$flag] = $flag;
}
ksort($flags, SORT_STRING);
return array_values($flags);
}
/** @param list<string> $flags */
private static function qualityMask(array $flags): int
{
$mask = 0;
foreach ($flags as $flag) {
$mask |= self::QUALITY_BITS[$flag];
}
return $mask;
}
/** @return array<string,mixed> */
private static function decodeObject(string $json, string $label): array
{
try {
$value = json_decode($json, true, 64, JSON_THROW_ON_ERROR);
} catch (\JsonException $error) {
throw new \RuntimeException(
'Invalid network abuse ' . $label,
0,
$error
);
}
if (!is_array($value) || array_is_list($value)) {
throw new \RuntimeException(
'Invalid network abuse ' . $label
);
}
return $value;
}
/** @param array<string,mixed> $value */
private static function json(array $value): string
{
return json_encode(
$value,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
| JSON_UNESCAPED_UNICODE
);
}
private static function add(int $left, int $right): int
{
if ($right > PHP_INT_MAX - $left) {
throw new \OverflowException(
'Network abuse daily counter overflowed'
);
}
return $left + $right;
}
}