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.
589 lines
22 KiB
PHP
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
|
|
);
|
|
}
|
|
}
|