Skip to content

feat(sdk): support sandbox network policies - #20

Closed
tianyuzhou95 wants to merge 1 commit into
inclusionAI:mainfrom
tianyuzhou95:albert/acl
Closed

feat(sdk): support sandbox network policies#20
tianyuzhou95 wants to merge 1 commit into
inclusionAI:mainfrom
tianyuzhou95:albert/acl

Conversation

@tianyuzhou95

Copy link
Copy Markdown
Collaborator

Summary

This PR adds creation-time network ACLs to the public Python SDK and enables
ACL enforcement in the bundled AKernel deployments.

Callers can leave sandbox networking unrestricted, block all network traffic
except the YuanRong control proxy, or deny selected DNS names:

from akernel_sdk import NetworkPolicy, Sandbox

Sandbox()
Sandbox(network=NetworkPolicy.block())
Sandbox(network=NetworkPolicy.deny_dns("github.com", "*.github.com"))

Omitting network, or passing an empty NetworkPolicy, preserves the existing
unrestricted behavior and does not send a policy to the runtime.

SDK and runtime behavior

NetworkPolicy is a backend-independent AKernel value type. The SDK validates
and normalizes DNS patterns before sandbox creation, lowercases names, removes
trailing dots, and deduplicates entries. Exact patterns match only the named
domain; a leading *. pattern matches descendants but not the apex. Block mode
and DNS blacklist mode are currently mutually exclusive.

Both supported YuanRong backends translate the public type into their native
wire representation. In block mode, lifecycle and command operations remain
available through the YuanRong control proxy. Filesystem operations fall back
to the RuntimeRPC data path instead of the direct node route, so large file
transfers may be slower.

The bundled standalone, Helm, and Terraform configurations enable sandboxd
network ACL support. The deployment documentation describes the required TC
eBPF and bpffs capabilities, DNS proxy port requirements, and the need to drain
existing sandboxes before enabling ACLs on an existing node.

This PR also updates the sandboxd submodule URL to
akernel-dev/sandboxd and pins the ACL-enabled main revision.

Limitations

  • Policies are fixed when the sandbox is created and cannot currently be
    changed through the SDK.
  • Packet ACL enforcement is IPv4 and stateless.
  • DNS blacklist rules cover conventional UDP and TCP DNS queries. DNS over
    HTTPS and direct connections to a known IP address are outside their scope.
  • block_network and dns_blacklist cannot be combined in one policy.

Validation

End-to-end validation on the test node covered all required modes:

  • A sandbox created without a policy retained unrestricted networking.
  • Block mode denied external traffic while YuanRong command, lifecycle, and
    filesystem operations remained available.
  • A DNS blacklist denied lookups for github.com while non-blacklisted names
    remained resolvable.

AKernel SDK validation completed successfully against the coordinated
sandbox-sdk source used for the test-node build:

  • 106 Python unit tests passed.
  • Ruff passed.
  • Mypy passed for all 21 SDK source files.

Draft follow-ups

This PR is ready for API and implementation review, but the YuanRong release
artifacts are not available yet. Before marking the PR ready for merge:

  • Replace the temporary src/yuanrong gitlink with the official YuanRong
    superproject revision containing the Frontend, FunctionSystem, and
    sandbox-sdk changes.
  • Replace the provisional openyuanrong-sandbox==0.10.0 dependency with the
    actual published version.
  • Update OPEN_YR_VERSION and the checksum-pinned openYuanRong core wheel for
    both supported architectures.
  • Re-run make sdk-check, the all-in-one image build, and end-to-end ACL tests
    using only the published artifacts.

Expose unrestricted, block-network, and DNS-deny modes through the stable
Python SDK. Enable sandboxd ACLs in bundled deployments and document the
runtime requirements, limitations, upgrade procedure, and maintained example.

Pin sandboxd to the ACL-enabled main revision. Keep the YuanRong submodule at
a public placeholder revision until the control-plane changes are released
and their final package versions and checksums can be recorded.

Signed-off-by: Tianyu Zhou <albert.zty@antgroup.com>
@tianyuzhou95

Copy link
Copy Markdown
Collaborator Author

re-implement in #22

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant