The Egress Proxy

Every request a box sends to the internet leaves through the Egress Proxy, which runs outside the box. It allows only what your org’s policy names, and refuses the rest. Nothing in the box can turn it off, an agent included.

What your box may reach

Your org’s Awake admin sets what boxes may reach, in Admin → Policies:

• Access sets each box’s tier and posture: how much of the internet a box may reach, and how.
• Destinations lists the hosts your org allows, beside Awake’s own sets, such as package registries and documentation sites. A destination may allow some methods or paths and not others, or need an approval first. It may also be a wildcard, such as *.googleapis.com: a tunnel to every host under the domain, but not to the domain itself. A host listed on its own keeps its own rules under a wildcard.

A host no destination names is refused. Where your org lets members ask, you can ask for one in Requests, and the answer names who approves it.

Your org can also keep exceptions: hosts, or every host under a domain, that it refuses whatever else allows them, Awake’s own sets included. The proxy refuses an excepted host with egress.exception, and no request in Requests opens it.

How a refusal reads

When the proxy refuses a request, it answers 403 with a body such as this one:

{"code":"permission_denied","reason":"not_allowed","message":"the box's egress policy doesn't allow this destination","docs":"https://docs.awake.computer/errors/egress.not_allowed"}

• reason is why: the refusal’s code is egress. and the reason, here egress.not_allowed.
• message says what happened and, often, what to try first.
• docs is the code’s page on this site.

The answer’s headers say the same: Link names the code’s page as help, and Proxy-Status names the code in its details.

Link: <https://docs.awake.computer/errors/egress.not_allowed>; rel="help"
Proxy-Status: awake-egress; error=http_request_denied; details="egress.not_allowed"

Most tools print only the status of a refused CONNECT, the first step of every https request through a proxy, so you may see only 403. A tool says the proxy refused its tunnel says how to find the code.

Plain HTTP and other protocols

Your org’s open egress setting decides which protocols a box may use to the destinations it may reach. Open, the default, allows any protocol, unless a box’s posture is Offline:

• plain http to a destination’s host, under the same rules as its https: the same methods, paths and approvals;
• on another port your org lists for a host, such as github.com on port 22 for git over SSH, any protocol in a tunnel.

A tunnel to port 443 still starts with TLS that names its host, or the proxy closes it, egress.not_tls. A tool that sends an http:// request as a tunnel to port 80, as some Node.js clients do, is refused, egress.not_allowed: use https.

Strict takes every box back to https only. Where the setting is strict, under the Offline posture, while your org’s policy checks requests for secrets, and wherever Awake adds your org’s own credential, a plain http request is refused, egress.plain_http: use https. Its page says what your admin can change, and where.

Secrets and credentials

A request may carry one of your secrets as its placeholder. The proxy swaps the placeholder for the secret’s value only on the hosts the secret is added on, and refuses it anywhere else: egress.placeholder_elsewhere and egress.secret_expired. For a destination your org binds, the proxy adds your org’s own credential on the way out: egress.credential_in_query and egress.no_grant.

Where Awake records it

The Egress Proxy records each refusal, never the request’s data. Org admins and security auditors read the records in the Audit log.

For agents

When the proxy refuses a request, tell the person what was refused and why, with the code from the answer’s reason. Don’t retry in a loop, and don’t try another host, encoding or route to get around the refusal.

Every egress code

Error codes lists the Egress Proxy’s codes, each with its page.