Feature: expose runtime network policy updates for Harbor phase-scoped ACLs

[1shuimo]

Summary

Harbor supports phase-scoped network policies for long-lived sandbox environments. A single sandbox may use:

1. An environment baseline policy.
2. A temporary policy while the agent runs.
3. A different policy while the verifier runs.
4. Restoration of the baseline after each phase.

Supporting this requires an environment provider to update the network policy of an already-running sandbox without recreating it.

AKernel currently allows AForge to provide a create-time ACL through sandbox configuration, but the AKernel Python SDK/control-plane API used by AForge does not expose a public runtime network-policy update operation.

Therefore, the AKernel Harbor backend must currently advertise:

dynamic_network_policy = False

Harbor rejects tasks whose agent or verifier policy differs from the environment baseline.

We would like AKernel to expose runtime network-policy replacement through its public API and Python SDK.

Harbor requirement

Harbor models network access using three layers:

• Environment baselines, installed when an environment starts.
• Agent/verifier phase overrides.
• Runtime allowlist additions supplied by the job.

If a phase policy differs from its baseline, Harbor requires the environment provider to support dynamic_network_policy; otherwise the task is rejected before execution.

Relevant Harbor sources:

• Harbor network policy documentation
• EnvironmentCapabilities.dynamic_network_policy
• BaseEnvironment.set_network_policy()
• Harbor phase switching and baseline restoration

Harbor applies a phase override approximately as follows:

await environment.set_network_policy(phase_policy)
try:
    await run_phase()
finally:
    await environment.set_network_policy(baseline_policy)

The sandbox process, filesystem, services, mounts, and identity must remain unchanged during this transition.

Official Harbor example

Harbor includes a shared-allowlist example where the agent and verifier run in the same sandbox with different allowlists:

[environment]
network_mode = "no-network"

[agent]
network_mode = "allowlist"
allowed_hosts = ["example.com", "*.amazonaws.com"]

[verifier]
network_mode = "allowlist"
allowed_hosts = ["*.iana.org"]
environment_mode = "shared"

Official example:

• Shared allowlist task
• Example description

The expected policy sequence for the same sandbox is:

environment baseline: deny all
    -> agent phase: allow example.com and *.amazonaws.com
    -> restore environment baseline
    -> verifier phase: allow *.iana.org
    -> restore environment baseline

During verification, destinations that were allowed only during the agent phase must no longer be reachable.

Harbor also provides a simpler example where an offline baseline is temporarily changed to public access during the agent phase and restored before verification:

• Environment baseline / agent override example

Current AKernel behavior

In the AKernel integration currently used by AForge:

• The effective ACL is compiled before sandbox creation.
• It is passed through the sandbox creation configuration.
• The policy remains fixed for the lifetime of the sandbox.
• Changing the policy requires destroying and recreating the sandbox.
• Recreating the sandbox is incompatible with Harbor shared agent/verifier execution because it loses live process and environment state.

Versions currently used by AForge:

akernel-sdk: 0.9.29
openyuanrong-sdk: 0.9.9
harbor: 0.13.2

Existing sandboxd support

The latest sandboxd network ACL implementation already provides most of the required runtime semantics through SetNetworkPolicy.

According to the sandboxd network ACL documentation:

• A policy can be installed after the sandbox reaches the running state.
• SetNetworkPolicy atomically replaces the complete policy.
• Omitting the policy clears the ACL and returns the sandbox to unrestricted networking.
• Existing connection state admitted by the previous policy generation is invalidated.
• Policy state is persisted and restored without a fail-open recovery window.

Therefore, the likely missing piece is exposing this capability through the complete AKernel path:

AKernel Python SDK
    -> AKernel gateway/control plane
    -> scheduled sandbox/node
    -> sandboxd SetNetworkPolicy

Callers should not need direct access to the node-local sandboxd endpoint.

Proposed API

The exact API shape is open for discussion. Conceptually, the SDK needs an operation such as:

await sandbox.set_network_policy(policy)

or:

await sandbox.network.set_policy(policy)

The operation should replace the complete policy of a running sandbox.

It should clearly distinguish between:

public / cleared policy
    No ACL; unrestricted network.

no-network
    Explicit deny-all policy.

allowlist
    Default deny with explicitly allowed destinations.

The same destination types supported during sandbox creation should be accepted during runtime updates, or unsupported combinations should fail explicitly.

Required semantics

Atomic replacement

A successful response must mean the new policy is already active.

Traffic must never observe a partially installed mixture of the old and new rules.

No sandbox restart

Updating the policy must preserve:

• Sandbox ID.
• Running processes and local services.
• Filesystem state.
• Mounts.
• Assigned resources.
• Reverse tunnels and other sandbox lifecycle state.

Immediate revocation

Connections authorized by the previous policy must not remain usable after a more restrictive policy has been acknowledged.

This is important when switching from the agent allowlist to the verifier allowlist.

Fail closed

If an update cannot be applied, the API must return an error.

It must not report success while leaving the sandbox unrestricted or retaining an unknown partial policy.

Idempotency

Retrying the same complete policy after a timeout should be safe.

A policy hash or generation number in the request and response would also help callers correlate updates and audit state.

Capability discovery

The SDK should expose whether runtime network-policy updates are supported for the selected backend and runtime.

Unsupported runtimes should reject the operation explicitly rather than ignoring it.

Observability

For troubleshooting and security auditing, the update should record at least:

• Sandbox ID.
• Old and new policy generation or hash.
• Update result.
• Enforcement backend.
• Rejection reason, if any.

The SDK should ideally allow callers to read the currently active policy or its generation/hash.

Reproduction and validation scenario

Using one running sandbox:

1. Start with an explicit deny-all baseline.
2. Confirm example.com and www.iana.org are unreachable.
3. Replace the policy with an agent allowlist containing example.com.
4. Confirm example.com is reachable and www.iana.org remains blocked.
5. Replace it with a verifier allowlist containing www.iana.org.
6. Confirm www.iana.org is reachable and example.com is now blocked.
7. Restore deny-all and confirm both are blocked.
8. Clear the policy and confirm unrestricted access is restored.
9. Verify that a local process started before step 3 remains alive throughout all transitions.

Acceptance criteria

• A public AKernel SDK API can replace the network policy of a running sandbox.
• The request is routed securely to the correct node and sandbox.
• Replacement is atomic and acknowledged only after enforcement.
• Tightening a policy invalidates connections admitted by the previous policy.
• Explicit deny-all and unrestricted/cleared policy have distinct semantics.
• Unsupported runtime/backend combinations fail explicitly.
• Concurrent or stale updates have deterministic behavior.
• Unit tests cover validation, idempotency, clearing, and error propagation.
• Integration tests cover allowlist-to-allowlist and public/deny-all transitions.
• The Harbor AKernel provider can advertise dynamic_network_policy=True.
• Harbor's official dynamic/shared-allowlist example passes on AKernel without recreating the sandbox.

Impact

Without this capability, AKernel cannot execute Harbor tasks that use different network boundaries for agent and verifier phases in a shared environment.

Keeping a single permissive policy for the entire trial would expose verifier-only services to the agent or retain agent-only destinations during verification.

Recreating the sandbox between phases is also insufficient because Harbor expects shared runtime and filesystem state.

Runtime ACL replacement lets AKernel preserve Harbor's execution semantics while maintaining least-privilege network access during every phase.

[tianyuzhou95]

Implemented in #40

[tianyuzhou95]

Already supported.