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/CloudAbuseObservationContra...

589 lines
22 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Strict trust boundary for aggregate, payload-free Agent observations.
*
* The returned value is rebuilt field by field. Callers must never persist the
* original Agent response because an unrecognised field could contain flow
* identities or packet content outside the reviewed contract.
*/
final class CloudAbuseObservationContract
{
public const CONTRACT_VERSION = 1;
public const BUCKET_SECONDS = 60;
public const MAX_WINDOWS = 64;
private const MAX_ENCODED_BYTES = 524288;
private const MAX_NODES = 20000;
private const MAX_DEPTH = 8;
private const CAPABILITY_NAME = 'network_abuse_observation_v1';
private const QUALITY_FLAGS = [
'clock_regression',
'cold_start',
'conntrack_unavailable',
'counter_reset',
'flow_limit_reached',
'incomplete',
'interface_unavailable',
'local_port_cardinality_saturated',
'mapping_changed',
'overflow',
'packet_accounting_unavailable',
'relation_cardinality_saturated',
'remote_ip_cardinality_saturated',
'remote_port_cardinality_saturated',
'sampling_gap',
];
private const RISK_UNSAFE_QUALITY_FLAGS = [
'clock_regression',
'cold_start',
'conntrack_unavailable',
'counter_reset',
'flow_limit_reached',
'incomplete',
'interface_unavailable',
'local_port_cardinality_saturated',
'mapping_changed',
'overflow',
'relation_cardinality_saturated',
'remote_ip_cardinality_saturated',
'remote_port_cardinality_saturated',
'sampling_gap',
];
private const CAPABILITY_REASONS = [
'probe_unavailable',
'permission_denied',
'netlink_unavailable',
'conntrack_unavailable',
'address_family_unavailable',
'probe_failed',
];
private const FLOW_FIELDS = [
'tcp_active_flows',
'tcp_new_flows',
'tcp_syn_flows',
'tcp_unreplied_flows',
'udp_active_flows',
'udp_new_flows',
'other_active_flows',
'unique_remote_ips',
'unique_remote_ports',
'unique_local_ports',
'max_remote_ports_per_remote_ip',
'max_remote_ips_per_remote_port',
'max_local_ports_per_remote_ip',
'max_remote_ips_per_local_port',
];
public static function normalize(
array $payload,
?string $requestedGeneration = null,
int $afterCursor = 0
): array {
if ($requestedGeneration !== null
&& preg_match('/^[a-f0-9]{32}$/D', $requestedGeneration) !== 1) {
throw new \InvalidArgumentException(
'Invalid requested network-observation generation'
);
}
if ($afterCursor < 0
|| ($requestedGeneration === null && $afterCursor !== 0)) {
throw new \InvalidArgumentException(
'Invalid requested network-observation cursor'
);
}
self::assertBoundedTree($payload);
self::assertObject($payload, [
'contract_version', 'collector_generation', 'oldest_cursor',
'gap_before', 'next_cursor', 'has_more', 'capability', 'windows',
], [], 'batch');
$version = self::unsigned($payload['contract_version'], 'contract_version');
$generation = self::patternString(
$payload['collector_generation'],
'/^[a-f0-9]{32}$/D',
'collector_generation'
);
if ($version !== self::CONTRACT_VERSION) {
self::invalid('unsupported contract_version');
}
$oldest = self::unsigned($payload['oldest_cursor'], 'oldest_cursor');
$gapBefore = self::boolean($payload['gap_before'], 'gap_before');
$next = self::unsigned($payload['next_cursor'], 'next_cursor');
$hasMore = self::boolean($payload['has_more'], 'has_more');
$capability = self::normalizeCapability($payload['capability']);
if (!is_array($payload['windows']) || !array_is_list($payload['windows'])
|| count($payload['windows']) > self::MAX_WINDOWS) {
self::invalid('windows is not a bounded list');
}
$windows = [];
$previous = 0;
foreach ($payload['windows'] as $index => $window) {
$normalized = self::normalizeWindow(
$window,
$generation,
$capability,
"windows[{$index}]"
);
if ($previous !== 0 && ($previous === PHP_INT_MAX
|| $normalized['cursor'] !== $previous + 1)) {
self::invalid('window cursors are not contiguous');
}
$previous = $normalized['cursor'];
$windows[] = $normalized;
}
if (!$capability['available'] && $windows !== []) {
self::invalid('unavailable capability returned windows');
}
if ($windows === []) {
if ($hasMore || $next !== 0 || $gapBefore) {
self::invalid('empty batch has pagination state');
}
} else {
$first = $windows[0]['cursor'];
if ($oldest === 0 || $oldest > $first) {
self::invalid('invalid retained cursor boundary');
}
if ($gapBefore && $oldest !== $first) {
self::invalid('gap batch does not start at retained boundary');
}
if ($next !== $previous || ($hasMore && $next === 0)) {
self::invalid('invalid next cursor');
}
}
$sameGeneration = $requestedGeneration !== null
&& hash_equals($requestedGeneration, $generation);
if ($windows === []) {
if (!$sameGeneration && $oldest !== 0) {
self::invalid(
'initial or reset empty batch retained a cursor boundary'
);
}
if ($sameGeneration && $oldest !== 0 && $oldest > $afterCursor) {
self::invalid(
'empty batch retained a boundary after the requested cursor'
);
}
}
if (($requestedGeneration === null || !$sameGeneration) && $gapBefore) {
self::invalid('generation reset retained an old-generation gap');
}
if ((!$sameGeneration || $afterCursor === 0) && $windows !== []
&& $windows[0]['cursor'] !== $oldest) {
self::invalid(
'initial or reset batch skipped the retained cursor boundary'
);
}
if ($sameGeneration && $windows !== []) {
$first = $windows[0]['cursor'];
if ($first <= $afterCursor) {
self::invalid('batch did not advance the requested cursor');
}
$expectedGap = $afterCursor > 0
&& $oldest > 0
&& $afterCursor < $oldest - 1;
if ($gapBefore !== $expectedGap) {
self::invalid('gap evidence disagrees with requested cursor');
}
if (!$gapBefore && $afterCursor > 0
&& ($afterCursor === PHP_INT_MAX
|| $first !== $afterCursor + 1)) {
self::invalid('batch skipped a cursor without gap evidence');
}
}
return [
'contract_version' => $version,
'collector_generation' => $generation,
'oldest_cursor' => $oldest,
'gap_before' => $gapBefore,
'next_cursor' => $next,
'has_more' => $hasMore,
'capability' => $capability,
'windows' => $windows,
];
}
private static function normalizeCapability(mixed $value): array
{
self::assertObject($value, [
'name', 'contract_version', 'available', 'no_payload', 'ipv4',
'ipv6', 'conntrack', 'packet_accounting', 'policy_decisions',
'bucket_seconds',
], ['reason'], 'capability');
$result = [
'name' => self::shortString($value['name'], 'capability.name'),
'contract_version' => self::unsigned(
$value['contract_version'], 'capability.contract_version'
),
'available' => self::boolean(
$value['available'], 'capability.available'
),
'no_payload' => self::boolean(
$value['no_payload'], 'capability.no_payload'
),
'ipv4' => self::boolean($value['ipv4'], 'capability.ipv4'),
'ipv6' => self::boolean($value['ipv6'], 'capability.ipv6'),
'conntrack' => self::boolean(
$value['conntrack'], 'capability.conntrack'
),
'packet_accounting' => self::boolean(
$value['packet_accounting'], 'capability.packet_accounting'
),
'policy_decisions' => self::boolean(
$value['policy_decisions'], 'capability.policy_decisions'
),
'bucket_seconds' => self::unsigned(
$value['bucket_seconds'], 'capability.bucket_seconds'
),
];
if ($result['name'] !== self::CAPABILITY_NAME
|| $result['contract_version'] !== self::CONTRACT_VERSION
|| !$result['no_payload']
|| $result['policy_decisions']
|| $result['bucket_seconds'] !== self::BUCKET_SECONDS) {
self::invalid('inconsistent capability contract');
}
if ($result['available']) {
if (array_key_exists('reason', $value)
|| !$result['conntrack']
|| (!$result['ipv4'] && !$result['ipv6'])) {
self::invalid('inconsistent available capability');
}
} else {
if (!array_key_exists('reason', $value)) {
self::invalid('unavailable capability omitted its reason');
}
$reason = self::shortString($value['reason'], 'capability.reason');
if (!in_array($reason, self::CAPABILITY_REASONS, true)) {
self::invalid('unknown capability reason');
}
$result['reason'] = $reason;
}
return $result;
}
private static function normalizeWindow(
mixed $value,
string $generation,
array $capability,
string $path
): array {
self::assertObject($value, [
'cursor', 'window_id', 'vm_uuid', 'bucket_start',
'bucket_seconds', 'complete', 'quality_flags', 'interface',
'ipv4', 'ipv6',
], [], $path);
$cursor = self::positive($value['cursor'], "{$path}.cursor");
$windowId = self::patternString(
$value['window_id'], '/^[a-f0-9]{32}$/D', "{$path}.window_id"
);
$uuid = self::patternString(
$value['vm_uuid'],
'/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/D',
"{$path}.vm_uuid"
);
[$bucketStart, $bucketEpoch] = self::bucketStart(
$value['bucket_start'], "{$path}.bucket_start"
);
$bucketSeconds = self::unsigned(
$value['bucket_seconds'], "{$path}.bucket_seconds"
);
if ($bucketSeconds !== self::BUCKET_SECONDS) {
self::invalid("{$path} uses an unsupported bucket size");
}
$expectedId = substr(hash('sha256', $generation . "\n" . $cursor
. "\n" . $uuid . "\n" . $bucketEpoch), 0, 32);
if (!hash_equals($expectedId, $windowId)) {
self::invalid("{$path}.window_id does not match its identity");
}
$complete = self::boolean($value['complete'], "{$path}.complete");
$quality = self::normalizeQualityFlags(
$value['quality_flags'], "{$path}.quality_flags"
);
$incomplete = in_array('incomplete', $quality, true);
if ($complete === $incomplete) {
self::invalid("{$path} completeness disagrees with quality flags");
}
if ($complete
&& array_intersect($quality, self::RISK_UNSAFE_QUALITY_FLAGS) !== []) {
self::invalid("{$path} contains risk-unsafe complete evidence");
}
$interface = self::normalizeInterface(
$value['interface'], "{$path}.interface"
);
$hasMissingCounter = in_array(null, $interface, true);
if ($hasMissingCounter
!== in_array('interface_unavailable', $quality, true)) {
self::invalid("{$path} interface availability is contradictory");
}
$ipv4 = self::normalizeFamily(
$value['ipv4'], $capability['ipv4'], "{$path}.ipv4"
);
$ipv6 = self::normalizeFamily(
$value['ipv6'], $capability['ipv6'], "{$path}.ipv6"
);
if ($ipv4 === null && $ipv6 === null) {
self::invalid("{$path} has no supported address family");
}
return [
'cursor' => $cursor,
'window_id' => $windowId,
'vm_uuid' => $uuid,
'bucket_start' => $bucketStart,
'bucket_seconds' => $bucketSeconds,
'complete' => $complete,
'quality_flags' => $quality,
'interface' => $interface,
'ipv4' => $ipv4,
'ipv6' => $ipv6,
];
}
private static function normalizeQualityFlags(mixed $value, string $path): array
{
if (!is_array($value) || !array_is_list($value) || count($value) > 16) {
self::invalid("{$path} is not a bounded list");
}
$result = [];
foreach ($value as $flag) {
$flag = self::shortString($flag, $path);
if (!in_array($flag, self::QUALITY_FLAGS, true)) {
self::invalid("{$path} contains an unknown flag");
}
$result[] = $flag;
}
$canonical = array_values(array_unique($result));
sort($canonical, SORT_STRING);
if ($canonical !== $result) {
self::invalid("{$path} is not canonical");
}
return $result;
}
private static function normalizeInterface(mixed $value, string $path): array
{
$fields = [
'rx_bytes', 'tx_bytes', 'rx_packets', 'tx_packets',
'rx_errors', 'tx_errors', 'rx_drops', 'tx_drops',
];
self::assertObject($value, $fields, [], $path);
$result = [];
foreach ($fields as $field) {
$result[$field] = $value[$field] === null
? null : self::unsigned($value[$field], "{$path}.{$field}");
}
return $result;
}
private static function normalizeFamily(
mixed $value,
bool $supported,
string $path
): ?array {
if (!$supported) {
if ($value !== null) {
self::invalid("{$path} is present without capability support");
}
return null;
}
if ($value === null) {
self::invalid("{$path} is missing despite capability support");
}
self::assertObject($value, ['inbound', 'outbound'], [], $path);
return [
'inbound' => self::normalizeFlowSummary(
$value['inbound'], "{$path}.inbound"
),
'outbound' => self::normalizeFlowSummary(
$value['outbound'], "{$path}.outbound"
),
];
}
private static function normalizeFlowSummary(mixed $value, string $path): array
{
self::assertObject($value, self::FLOW_FIELDS, [], $path);
$result = [];
foreach (self::FLOW_FIELDS as $field) {
$result[$field] = self::unsigned($value[$field], "{$path}.{$field}");
}
if ($result['tcp_new_flows'] > $result['tcp_active_flows']
|| $result['tcp_syn_flows'] > $result['tcp_active_flows']
|| $result['tcp_unreplied_flows'] > $result['tcp_active_flows']
|| $result['udp_new_flows'] > $result['udp_active_flows']) {
self::invalid("{$path} contains an impossible flow subset");
}
if ($result['tcp_active_flows'] > PHP_INT_MAX - $result['udp_active_flows']) {
self::invalid("{$path} active-flow population overflowed");
}
$total = $result['tcp_active_flows'] + $result['udp_active_flows'];
if ($total > PHP_INT_MAX - $result['other_active_flows']) {
self::invalid("{$path} active-flow population overflowed");
}
$total += $result['other_active_flows'];
if ($result['unique_remote_ips'] > $total
|| $result['unique_remote_ports'] > $total
|| $result['unique_local_ports'] > $total
|| $result['max_remote_ports_per_remote_ip']
> $result['unique_remote_ports']
|| $result['max_remote_ips_per_remote_port']
> $result['unique_remote_ips']
|| $result['max_local_ports_per_remote_ip']
> $result['unique_local_ports']
|| $result['max_remote_ips_per_local_port']
> $result['unique_remote_ips']) {
self::invalid("{$path} contains an impossible cardinality");
}
if (($result['unique_remote_ips'] === 0
&& ($result['max_remote_ports_per_remote_ip'] !== 0
|| $result['max_local_ports_per_remote_ip'] !== 0))
|| ($result['unique_remote_ports'] === 0
&& $result['max_remote_ips_per_remote_port'] !== 0)
|| ($result['unique_local_ports'] === 0
&& $result['max_remote_ips_per_local_port'] !== 0)) {
self::invalid("{$path} relation cardinality has no population");
}
return $result;
}
private static function assertBoundedTree(array $payload): void
{
try {
$encoded = json_encode(
$payload,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
} catch (\JsonException) {
self::invalid('response cannot be encoded canonically');
}
if (strlen($encoded) > self::MAX_ENCODED_BYTES) {
self::invalid('response exceeds the observation size limit');
}
$nodes = 0;
$stack = [[$payload, 1]];
while ($stack !== []) {
[$value, $depth] = array_pop($stack);
if (++$nodes > self::MAX_NODES || $depth > self::MAX_DEPTH) {
self::invalid('response exceeds the observation shape limit');
}
if (!is_array($value)) {
continue;
}
foreach ($value as $child) {
$stack[] = [$child, $depth + 1];
}
}
}
private static function assertObject(
mixed $value,
array $required,
array $optional,
string $path
): void {
if (!is_array($value) || $value === [] || array_is_list($value)) {
self::invalid("{$path} is not an object");
}
$allowed = array_fill_keys(array_merge($required, $optional), true);
foreach (array_keys($value) as $key) {
if (!is_string($key) || !isset($allowed[$key])) {
self::invalid("{$path} contains an unknown field");
}
}
foreach ($required as $key) {
if (!array_key_exists($key, $value)) {
self::invalid("{$path} omitted a required field");
}
}
}
private static function unsigned(mixed $value, string $path): int
{
if (!is_int($value) || $value < 0) {
self::invalid("{$path} is not an unsigned integer");
}
return $value;
}
private static function positive(mixed $value, string $path): int
{
$value = self::unsigned($value, $path);
if ($value === 0) {
self::invalid("{$path} must be positive");
}
return $value;
}
private static function boolean(mixed $value, string $path): bool
{
if (!is_bool($value)) {
self::invalid("{$path} is not a boolean");
}
return $value;
}
private static function shortString(mixed $value, string $path): string
{
if (!is_string($value) || $value === '' || strlen($value) > 64
|| preg_match('/[\x00-\x1f\x7f]/', $value) === 1) {
self::invalid("{$path} is not a bounded string");
}
return $value;
}
private static function patternString(
mixed $value,
string $pattern,
string $path
): string {
if (!is_string($value) || preg_match($pattern, $value) !== 1) {
self::invalid("{$path} has an invalid format");
}
return $value;
}
private static function bucketStart(mixed $value, string $path): array
{
if (!is_string($value)
|| preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:00Z$/D', $value) !== 1) {
self::invalid("{$path} is not a UTC minute");
}
$time = \DateTimeImmutable::createFromFormat(
'!Y-m-d\TH:i:s\Z',
$value,
new \DateTimeZone('UTC')
);
$errors = \DateTimeImmutable::getLastErrors();
if ($time === false || ($errors !== false
&& ($errors['warning_count'] !== 0 || $errors['error_count'] !== 0))
|| $time->format('Y-m-d\TH:i:s\Z') !== $value
|| $time->getTimestamp() < 0
|| $time->getTimestamp() % self::BUCKET_SECONDS !== 0) {
self::invalid("{$path} is not a canonical UTC minute");
}
return [$value, $time->getTimestamp()];
}
private static function invalid(string $reason): never
{
throw new CloudAgentError(
'宿主机 Agent 返回了无效的网络观测合同',
502,
'agent_invalid_network_observation',
true
);
}
}