feat(cloud): validate signed abuse observation batches
parent
5ad82fd3ff
commit
0fc3a9c568
@ -0,0 +1,588 @@
|
||||
<?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
|
||||
);
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,359 @@
|
||||
<?php
|
||||
|
||||
require dirname(__DIR__) . '/vendor/autoload.php';
|
||||
|
||||
use App\Services\Cloud\CloudAbuseObservationContract;
|
||||
use App\Services\Cloud\CloudAgentClient;
|
||||
use App\Services\Cloud\CloudAgentError;
|
||||
use App\Services\Cloud\CloudAgentGatewayEndpoint;
|
||||
use GuzzleHttp\Client;
|
||||
use GuzzleHttp\Handler\MockHandler;
|
||||
use GuzzleHttp\HandlerStack;
|
||||
use GuzzleHttp\Middleware;
|
||||
use GuzzleHttp\Psr7\Response;
|
||||
|
||||
$assert = static function (bool $condition, string $message): void {
|
||||
if (!$condition) {
|
||||
throw new RuntimeException($message);
|
||||
}
|
||||
};
|
||||
|
||||
$generation = '0123456789abcdef0123456789abcdef';
|
||||
$uuid = '123e4567-e89b-42d3-a456-426614174000';
|
||||
$bucket = '2026-11-08T01:02:00Z';
|
||||
$bucketEpoch = 1794099720;
|
||||
$flow = static fn (): array => [
|
||||
'tcp_active_flows' => 5,
|
||||
'tcp_new_flows' => 2,
|
||||
'tcp_syn_flows' => 1,
|
||||
'tcp_unreplied_flows' => 1,
|
||||
'udp_active_flows' => 3,
|
||||
'udp_new_flows' => 1,
|
||||
'other_active_flows' => 0,
|
||||
'unique_remote_ips' => 4,
|
||||
'unique_remote_ports' => 3,
|
||||
'unique_local_ports' => 2,
|
||||
'max_remote_ports_per_remote_ip' => 2,
|
||||
'max_remote_ips_per_remote_port' => 2,
|
||||
'max_local_ports_per_remote_ip' => 1,
|
||||
'max_remote_ips_per_local_port' => 2,
|
||||
];
|
||||
$valid = static function () use (
|
||||
$generation,
|
||||
$uuid,
|
||||
$bucket,
|
||||
$bucketEpoch,
|
||||
$flow
|
||||
): array {
|
||||
$cursor = 1;
|
||||
return [
|
||||
'contract_version' => 1,
|
||||
'collector_generation' => $generation,
|
||||
'oldest_cursor' => 1,
|
||||
'gap_before' => false,
|
||||
'next_cursor' => 1,
|
||||
'has_more' => false,
|
||||
'capability' => [
|
||||
'name' => 'network_abuse_observation_v1',
|
||||
'contract_version' => 1,
|
||||
'available' => true,
|
||||
'no_payload' => true,
|
||||
'ipv4' => true,
|
||||
'ipv6' => false,
|
||||
'conntrack' => true,
|
||||
'packet_accounting' => true,
|
||||
'policy_decisions' => false,
|
||||
'bucket_seconds' => 60,
|
||||
],
|
||||
'windows' => [[
|
||||
'cursor' => $cursor,
|
||||
'window_id' => substr(hash('sha256', $generation . "\n"
|
||||
. $cursor . "\n" . $uuid . "\n" . $bucketEpoch), 0, 32),
|
||||
'vm_uuid' => $uuid,
|
||||
'bucket_start' => $bucket,
|
||||
'bucket_seconds' => 60,
|
||||
'complete' => true,
|
||||
'quality_flags' => [],
|
||||
'interface' => [
|
||||
'rx_bytes' => 1000,
|
||||
'tx_bytes' => 2000,
|
||||
'rx_packets' => 10,
|
||||
'tx_packets' => 20,
|
||||
'rx_errors' => 0,
|
||||
'tx_errors' => 0,
|
||||
'rx_drops' => 0,
|
||||
'tx_drops' => 0,
|
||||
],
|
||||
'ipv4' => [
|
||||
'inbound' => $flow(),
|
||||
'outbound' => $flow(),
|
||||
],
|
||||
'ipv6' => null,
|
||||
]],
|
||||
];
|
||||
};
|
||||
|
||||
$normalized = CloudAbuseObservationContract::normalize($valid());
|
||||
$assert($normalized['collector_generation'] === $generation
|
||||
&& $normalized['windows'][0]['bucket_start'] === $bucket
|
||||
&& $normalized['windows'][0]['ipv4']['outbound']['tcp_new_flows'] === 2,
|
||||
'A valid observation batch was not preserved canonically.');
|
||||
$encoded = json_encode($normalized, JSON_THROW_ON_ERROR);
|
||||
$assert(!str_contains($encoded, '"payload":')
|
||||
&& !str_contains($encoded, '"remote_ip":"')
|
||||
&& !str_contains($encoded, 'remote_ports":['),
|
||||
'The normalized contract leaked flow identities or packet content.');
|
||||
|
||||
$reject = static function (array $payload, string $message) use ($assert): void {
|
||||
try {
|
||||
CloudAbuseObservationContract::normalize($payload);
|
||||
throw new RuntimeException($message);
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation'
|
||||
&& $error->httpStatus === 502
|
||||
&& $error->retryable,
|
||||
'Invalid network evidence lost its typed retryable failure.');
|
||||
}
|
||||
};
|
||||
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['payload'] = base64_encode('private packet body');
|
||||
$reject($payload, 'Packet payload field was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['ipv4']['outbound']['remote_ips'] = ['203.0.113.2'];
|
||||
$reject($payload, 'Remote-IP list field was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['ipv4']['outbound']['remote_ports'] = [22, 25];
|
||||
$reject($payload, 'Remote-port list field was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['ipv4']['outbound']['tcp_new_flows'] = 6;
|
||||
$reject($payload, 'Impossible TCP subset was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['ipv4']['outbound']['unique_remote_ips'] = 9;
|
||||
$reject($payload, 'Impossible remote cardinality was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['window_id'] = str_repeat('a', 32);
|
||||
$reject($payload, 'Window identity mismatch was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['bucket_start'] = '2026-11-08T01:02:01Z';
|
||||
$reject($payload, 'Non-minute bucket was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['quality_flags'] = ['clock_regression'];
|
||||
$reject($payload, 'Risk-unsafe complete window was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['interface']['rx_packets'] = null;
|
||||
$reject($payload, 'Missing interface counter without evidence was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['cursor'] = '1';
|
||||
$reject($payload, 'A string cursor was accepted as an integer.');
|
||||
$payload = $valid();
|
||||
$second = $payload['windows'][0];
|
||||
$second['cursor'] = 3;
|
||||
$second['window_id'] = substr(hash('sha256', $generation . "\n3\n"
|
||||
. $uuid . "\n" . $bucketEpoch), 0, 32);
|
||||
$payload['windows'][] = $second;
|
||||
$payload['next_cursor'] = 3;
|
||||
$reject($payload, 'A skipped cursor inside one batch was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['windows'] = array_fill(
|
||||
0,
|
||||
CloudAbuseObservationContract::MAX_WINDOWS + 1,
|
||||
$payload['windows'][0]
|
||||
);
|
||||
$reject($payload, 'Unbounded observation window list was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['oversized'] = str_repeat('x', 524289);
|
||||
$reject($payload, 'An oversized observation tree was accepted.');
|
||||
$payload = $valid();
|
||||
$payload['nested'] = [
|
||||
'a' => [
|
||||
'b' => [
|
||||
'c' => [
|
||||
'd' => [
|
||||
'e' => [
|
||||
'f' => [
|
||||
'g' => [
|
||||
'h' => ['i' => true],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
];
|
||||
$reject($payload, 'An over-deep observation tree was accepted.');
|
||||
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['complete'] = false;
|
||||
$payload['windows'][0]['quality_flags'] = ['incomplete', 'sampling_gap'];
|
||||
$normalizedGap = CloudAbuseObservationContract::normalize($payload);
|
||||
$assert($normalizedGap['windows'][0]['complete'] === false,
|
||||
'An explicit sampling gap was not retained as incomplete evidence.');
|
||||
|
||||
$payload = $valid();
|
||||
$payload['gap_before'] = true;
|
||||
$resetGeneration = 'fedcba9876543210fedcba9876543210';
|
||||
$tryReset = static function () use (
|
||||
$payload,
|
||||
$resetGeneration
|
||||
): void {
|
||||
CloudAbuseObservationContract::normalize($payload, $resetGeneration, 99);
|
||||
};
|
||||
try {
|
||||
$tryReset();
|
||||
throw new RuntimeException('Generation reset retained stale gap evidence.');
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation',
|
||||
'Generation-reset contradiction did not fail through the contract.');
|
||||
}
|
||||
|
||||
$payload = $valid();
|
||||
$payload['oldest_cursor'] = 3;
|
||||
$payload['windows'][0]['cursor'] = 3;
|
||||
$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n"
|
||||
. $uuid . "\n" . $bucketEpoch), 0, 32);
|
||||
$payload['next_cursor'] = 3;
|
||||
$payload['gap_before'] = true;
|
||||
$gap = CloudAbuseObservationContract::normalize($payload, $generation, 1);
|
||||
$assert($gap['gap_before'] && $gap['oldest_cursor'] === 3,
|
||||
'A truthful retained-ring gap was rejected.');
|
||||
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['cursor'] = 3;
|
||||
$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n"
|
||||
. $uuid . "\n" . $bucketEpoch), 0, 32);
|
||||
$payload['next_cursor'] = 3;
|
||||
try {
|
||||
CloudAbuseObservationContract::normalize($payload, $generation, 1);
|
||||
throw new RuntimeException('A same-generation cursor skip was accepted.');
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation',
|
||||
'A cursor skip did not fail through the strict contract.');
|
||||
}
|
||||
|
||||
$payload = $valid();
|
||||
$payload['windows'][0]['cursor'] = 3;
|
||||
$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n"
|
||||
. $uuid . "\n" . $bucketEpoch), 0, 32);
|
||||
$payload['next_cursor'] = 3;
|
||||
$reject($payload, 'An initial batch skipped the retained boundary.');
|
||||
try {
|
||||
CloudAbuseObservationContract::normalize(
|
||||
$payload,
|
||||
$generation,
|
||||
0
|
||||
);
|
||||
throw new RuntimeException(
|
||||
'A same-generation zero-cursor batch skipped the retained boundary.'
|
||||
);
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation',
|
||||
'A same-generation zero-cursor skip did not fail strictly.');
|
||||
}
|
||||
try {
|
||||
CloudAbuseObservationContract::normalize(
|
||||
$payload,
|
||||
'fedcba9876543210fedcba9876543210',
|
||||
88
|
||||
);
|
||||
throw new RuntimeException(
|
||||
'A generation-reset batch skipped the retained boundary.'
|
||||
);
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation',
|
||||
'A reset boundary skip did not fail through the strict contract.');
|
||||
}
|
||||
|
||||
$empty = $valid();
|
||||
$empty['windows'] = [];
|
||||
$empty['next_cursor'] = 0;
|
||||
$empty['oldest_cursor'] = 2;
|
||||
$reject($empty, 'An initial empty batch retained an impossible boundary.');
|
||||
try {
|
||||
CloudAbuseObservationContract::normalize($empty, $generation, 1);
|
||||
throw new RuntimeException(
|
||||
'A same-generation empty batch retained a future boundary.'
|
||||
);
|
||||
} catch (CloudAgentError $error) {
|
||||
$assert($error->agentCode === 'agent_invalid_network_observation',
|
||||
'A future empty boundary did not fail through the strict contract.');
|
||||
}
|
||||
$empty['oldest_cursor'] = 1;
|
||||
$normalizedEmpty = CloudAbuseObservationContract::normalize(
|
||||
$empty,
|
||||
$generation,
|
||||
1
|
||||
);
|
||||
$assert($normalizedEmpty['windows'] === []
|
||||
&& $normalizedEmpty['oldest_cursor'] === 1,
|
||||
'A truthful exhausted-ring empty batch was rejected.');
|
||||
|
||||
$history = [];
|
||||
$handler = new MockHandler([
|
||||
new Response(200, ['Content-Type' => 'application/json'], json_encode(
|
||||
$valid(),
|
||||
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
|
||||
)),
|
||||
]);
|
||||
$stack = HandlerStack::create($handler);
|
||||
$stack->push(Middleware::history($history));
|
||||
$client = new CloudAgentClient(
|
||||
'42',
|
||||
'test-secret-which-is-at-least-32-bytes',
|
||||
new Client(['handler' => $stack]),
|
||||
20.0,
|
||||
CloudAgentGatewayEndpoint::URL,
|
||||
'test-gateway-secret-at-least-32-bytes'
|
||||
);
|
||||
$result = $client->networkObservations([
|
||||
'user_id' => 1,
|
||||
'is_admin' => true,
|
||||
'is_super_admin' => true,
|
||||
'can_manage' => true,
|
||||
], null, 0, 64);
|
||||
$wire = json_decode(
|
||||
(string) $history[0]['request']->getBody(),
|
||||
true,
|
||||
16,
|
||||
JSON_THROW_ON_ERROR
|
||||
);
|
||||
$actorValue = (string) ($wire['headers']['X-Virt-Actor'] ?? '');
|
||||
$actorValue = strtr($actorValue, '-_', '+/');
|
||||
$actorValue .= str_repeat('=', (4 - strlen($actorValue) % 4) % 4);
|
||||
$signedActor = json_decode(
|
||||
base64_decode($actorValue, true),
|
||||
true,
|
||||
16,
|
||||
JSON_THROW_ON_ERROR
|
||||
);
|
||||
$assert(($wire['method'] ?? null) === 'GET'
|
||||
&& ($wire['request_target'] ?? null)
|
||||
=== '/v1/network-observations?after_cursor=0&limit=64'
|
||||
&& ($wire['body'] ?? null) === ''
|
||||
&& $signedActor === [
|
||||
'user_id' => 1,
|
||||
'is_admin' => true,
|
||||
'is_super_admin' => true,
|
||||
'can_manage' => true,
|
||||
]
|
||||
&& $result['windows'][0]['window_id']
|
||||
=== $valid()['windows'][0]['window_id'],
|
||||
'The read-only signed observation request changed its reviewed target.');
|
||||
|
||||
foreach ([
|
||||
[null, -1, 64],
|
||||
[null, 1, 64],
|
||||
[null, 0, 0],
|
||||
[null, 0, 65],
|
||||
['invalid', 0, 64],
|
||||
] as [$requestedGeneration, $after, $limit]) {
|
||||
try {
|
||||
$client->networkObservations([], $requestedGeneration, $after, $limit);
|
||||
throw new RuntimeException('Invalid observation pagination was accepted.');
|
||||
} catch (InvalidArgumentException $error) {
|
||||
// Expected before transport.
|
||||
}
|
||||
}
|
||||
|
||||
echo "Cloud abuse observation contract passed.\n";
|
||||
Loading…
Reference in New Issue