feat(cloud): validate signed abuse observation batches

go
codex 2 weeks ago
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
);
}
}

@ -174,6 +174,52 @@ final class CloudAgentClient
);
}
/**
* Read one bounded, aggregate network-observation page.
*
* This is intentionally not a cloud_jobs operation: it has no mutation,
* replay or lifecycle effect. The response crosses a dedicated strict
* parser so unknown Agent fields can never be persisted by callers.
*/
public function networkObservations(
array $actor,
?string $generation = null,
int $afterCursor = 0,
int $limit = CloudAbuseObservationContract::MAX_WINDOWS
): array {
if ($generation !== null
&& preg_match('/^[a-f0-9]{32}$/D', $generation) !== 1) {
throw new \InvalidArgumentException(
'Invalid network-observation generation'
);
}
if ($afterCursor < 0
|| ($generation === null && $afterCursor !== 0)
|| $limit < 1
|| $limit > CloudAbuseObservationContract::MAX_WINDOWS) {
throw new \InvalidArgumentException(
'Invalid network-observation pagination'
);
}
$query = [];
if ($generation !== null) {
$query['generation'] = $generation;
}
$query['after_cursor'] = (string) $afterCursor;
$query['limit'] = (string) $limit;
$target = '/v1/network-observations?' . http_build_query(
$query,
'',
'&',
PHP_QUERY_RFC3986
);
return CloudAbuseObservationContract::normalize(
$this->request('GET', $target, $actor),
$generation,
$afterCursor
);
}
/**
* Send one operation-bound recovery request with no human privileges.
*

@ -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…
Cancel
Save