@buildanagent/harness 0.1.0-alpha.28 → 0.1.0-alpha.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -5
- package/dist/context/file-spill.d.ts +11 -1
- package/dist/context/file-spill.js +23 -8
- package/dist/context/file-spill.js.map +1 -1
- package/dist/context/spill.d.ts +5 -1
- package/dist/context/spill.js +6 -2
- package/dist/context/spill.js.map +1 -1
- package/dist/credentials/addresses.d.ts +11 -0
- package/dist/credentials/addresses.js +41 -2
- package/dist/credentials/addresses.js.map +1 -1
- package/dist/credentials/allowlist.d.ts +22 -2
- package/dist/credentials/allowlist.js +74 -17
- package/dist/credentials/allowlist.js.map +1 -1
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +13 -1
- package/dist/credentials/egress-proxy.js +179 -11
- package/dist/credentials/egress-proxy.js.map +1 -1
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +5 -1
- package/dist/credentials/index.js +5 -1
- package/dist/credentials/index.js.map +1 -1
- package/dist/credentials/scrub.d.ts +7 -0
- package/dist/credentials/scrub.js +22 -0
- package/dist/credentials/scrub.js.map +1 -1
- package/dist/errors.d.ts +14 -7
- package/dist/errors.js +13 -6
- package/dist/errors.js.map +1 -1
- package/dist/sandbox/base.d.ts +11 -1
- package/dist/sandbox/base.js +14 -0
- package/dist/sandbox/base.js.map +1 -1
- package/dist/sandbox/docker/index.d.ts +8 -2
- package/dist/sandbox/docker/index.js +63 -14
- package/dist/sandbox/docker/index.js.map +1 -1
- package/dist/sandbox/errors.d.ts +30 -2
- package/dist/sandbox/errors.js +36 -1
- package/dist/sandbox/errors.js.map +1 -1
- package/dist/sandbox/escalation-table.d.ts +38 -0
- package/dist/sandbox/escalation-table.js +95 -0
- package/dist/sandbox/escalation-table.js.map +1 -0
- package/dist/sandbox/escalation.d.ts +191 -0
- package/dist/sandbox/escalation.js +370 -0
- package/dist/sandbox/escalation.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +2 -0
- package/dist/sandbox/host-files.js +10 -0
- package/dist/sandbox/host-files.js.map +1 -1
- package/dist/sandbox/index.d.ts +9 -4
- package/dist/sandbox/index.js +8 -3
- package/dist/sandbox/index.js.map +1 -1
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.js +1 -1
- package/dist/sandbox/process.js.map +1 -1
- package/dist/sandbox/srt/index.d.ts +5 -2
- package/dist/sandbox/srt/index.js +27 -8
- package/dist/sandbox/srt/index.js.map +1 -1
- package/dist/sandbox/srt/settings.d.ts +17 -5
- package/dist/sandbox/srt/settings.js +53 -0
- package/dist/sandbox/srt/settings.js.map +1 -1
- package/dist/sandbox/types.d.ts +41 -4
- package/dist/sandbox/types.js.map +1 -1
- package/dist/sandbox/widen.d.ts +10 -0
- package/dist/sandbox/widen.js +150 -0
- package/dist/sandbox/widen.js.map +1 -0
- package/dist/session/approvals.d.ts +30 -1
- package/dist/session/approvals.js +12 -4
- package/dist/session/approvals.js.map +1 -1
- package/dist/session/code-call.d.ts +15 -1
- package/dist/session/code-call.js +2 -1
- package/dist/session/code-call.js.map +1 -1
- package/dist/session/escalation-log.d.ts +65 -0
- package/dist/session/escalation-log.js +84 -0
- package/dist/session/escalation-log.js.map +1 -0
- package/dist/session/rebuild.js +12 -3
- package/dist/session/rebuild.js.map +1 -1
- package/dist/testing/fake-sandbox.d.ts +21 -3
- package/dist/testing/fake-sandbox.js +157 -8
- package/dist/testing/fake-sandbox.js.map +1 -1
- package/dist/testing/sandbox-conformance.js +108 -1
- package/dist/testing/sandbox-conformance.js.map +1 -1
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/index.d.ts +6 -2
- package/dist/tools/index.js +5 -2
- package/dist/tools/index.js.map +1 -1
- package/llms.txt +52 -0
- package/package.json +5 -5
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { HarnessError } from "../errors.js";
|
|
6
6
|
import { isAddressLiteral } from "./addresses.js";
|
|
7
|
+
import { checkGitFilter } from "./git-route.js";
|
|
7
8
|
const HOST_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
|
|
8
9
|
const ROUTE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
|
|
9
10
|
const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
|
|
@@ -49,29 +50,85 @@ export function parseAllow(entries) {
|
|
|
49
50
|
export function isAllowed(allow, host, port) {
|
|
50
51
|
return allow.some((entry) => entry.port === port && (entry.wildcard ? host.endsWith(`.${entry.name}`) : host === entry.name));
|
|
51
52
|
}
|
|
52
|
-
/**
|
|
53
|
-
|
|
53
|
+
/** Whether `name` is on the allowlist on any port, so a tunnel could reach it. */
|
|
54
|
+
const allowedOnAnyPort = (allow, name) => allow.some((entry) => (entry.wildcard ? name.endsWith(`.${entry.name}`) : name === entry.name));
|
|
55
|
+
/**
|
|
56
|
+
* The first git route that shares its host with a way around its filter, and what that way is: an allowlist entry, on
|
|
57
|
+
* any port, that lets a tunnel reach the host, or another route to the same host, which would carry a credential there
|
|
58
|
+
* without the git route's repository and ref checks. Hosts are compared in lower case without their ports.
|
|
59
|
+
*/
|
|
60
|
+
export function gitHostOverlap(routes, allow) {
|
|
61
|
+
const names = routes.map((route) => String(route.host)
|
|
62
|
+
.toLowerCase()
|
|
63
|
+
.replace(/:[0-9]*$/, ""));
|
|
64
|
+
for (const [index, route] of routes.entries()) {
|
|
65
|
+
if (route.git === undefined)
|
|
66
|
+
continue;
|
|
67
|
+
const name = names[index] ?? "";
|
|
68
|
+
if (allowedOnAnyPort(allow, name))
|
|
69
|
+
return { index, with: "allow" };
|
|
70
|
+
if (names.some((other, at) => at !== index && other === name))
|
|
71
|
+
return { index, with: "route" };
|
|
72
|
+
}
|
|
73
|
+
return undefined;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Parses and checks the routes against the parsed allowlist. It refuses two routes with one name, and a git route whose
|
|
77
|
+
* host is also on the allowlist or is another route's host, because either would go around its filter.
|
|
78
|
+
*/
|
|
79
|
+
export function parseRoutes(routes, allow) {
|
|
54
80
|
const seen = new Set();
|
|
55
|
-
|
|
81
|
+
const parsed = routes.map((route) => {
|
|
56
82
|
if (!ROUTE_NAME.test(route.route))
|
|
57
83
|
throw invalid(`the route name ${JSON.stringify(route.route)} is not usable`);
|
|
58
84
|
if (seen.has(route.route))
|
|
59
85
|
throw invalid(`two routes are named ${route.route}`);
|
|
60
86
|
seen.add(route.route);
|
|
61
|
-
|
|
62
|
-
if (!HOST_NAME.test(name) || isAddressLiteral(name))
|
|
63
|
-
throw invalid(`the route host ${route.host} must be a host name`);
|
|
64
|
-
const methods = route.methods.map((method) => method.toUpperCase());
|
|
65
|
-
if (methods.length === 0 || !methods.every((method) => METHOD.test(method)) || methods.includes("CONNECT")) {
|
|
66
|
-
throw invalid(`the route ${route.route} needs a list of methods, such as ["GET"]`);
|
|
67
|
-
}
|
|
68
|
-
const header = route.header.toLowerCase();
|
|
69
|
-
if (!HEADER_NAME.test(header) || RESERVED_HEADERS.has(header)) {
|
|
70
|
-
throw invalid(`the route ${route.route} can't carry its credential in the header ${route.header}`);
|
|
71
|
-
}
|
|
72
|
-
if (typeof route.secret !== "function")
|
|
73
|
-
throw invalid(`the route ${route.route} needs a secret function`);
|
|
74
|
-
return { route: route.route, hostname: name, port, methods: new Set(methods), header, secret: route.secret };
|
|
87
|
+
return parseRoute(route);
|
|
75
88
|
});
|
|
89
|
+
const overlap = gitHostOverlap(routes, allow);
|
|
90
|
+
if (overlap !== undefined) {
|
|
91
|
+
const name = routes[overlap.index]?.route ?? "";
|
|
92
|
+
throw invalid(overlap.with === "allow"
|
|
93
|
+
? `the host of the git route ${name} is also on the allowlist, so a tunnel could go around its filter`
|
|
94
|
+
: `the host of the git route ${name} is another route's host, which could go around its filter`);
|
|
95
|
+
}
|
|
96
|
+
return parsed;
|
|
97
|
+
}
|
|
98
|
+
/** Parses and checks one route's host, methods, header, secret and git filter. */
|
|
99
|
+
function parseRoute(route) {
|
|
100
|
+
const { name, port } = splitHost(route.host, "the route host");
|
|
101
|
+
if (!HOST_NAME.test(name) || isAddressLiteral(name))
|
|
102
|
+
throw invalid(`the route host ${route.host} must be a host name`);
|
|
103
|
+
const methods = route.methods.map((method) => method.toUpperCase());
|
|
104
|
+
if (methods.length === 0 || !methods.every((method) => METHOD.test(method)) || methods.includes("CONNECT")) {
|
|
105
|
+
throw invalid(`the route ${route.route} needs a list of methods, such as ["GET"]`);
|
|
106
|
+
}
|
|
107
|
+
const header = route.header.toLowerCase();
|
|
108
|
+
if (!HEADER_NAME.test(header) || RESERVED_HEADERS.has(header)) {
|
|
109
|
+
throw invalid(`the route ${route.route} can't carry its credential in the header ${route.header}`);
|
|
110
|
+
}
|
|
111
|
+
if (typeof route.secret !== "function")
|
|
112
|
+
throw invalid(`the route ${route.route} needs a secret function`);
|
|
113
|
+
if (route.git !== undefined)
|
|
114
|
+
checkGitRoute(route.git, methods, header);
|
|
115
|
+
return {
|
|
116
|
+
route: route.route,
|
|
117
|
+
hostname: name,
|
|
118
|
+
port,
|
|
119
|
+
methods: new Set(methods),
|
|
120
|
+
header,
|
|
121
|
+
secret: route.secret,
|
|
122
|
+
...(route.git === undefined ? {} : { git: route.git }),
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
/** Throws unless a git route carries its credential in `authorization` and takes exactly `GET` and `POST`. */
|
|
126
|
+
function checkGitRoute(filter, methods, header) {
|
|
127
|
+
checkGitFilter(filter);
|
|
128
|
+
if (header !== "authorization")
|
|
129
|
+
throw invalid("a git route carries its credential in the authorization header");
|
|
130
|
+
if (new Set(methods).size !== 2 || !methods.includes("GET") || !methods.includes("POST")) {
|
|
131
|
+
throw invalid("a git route takes the methods GET and POST");
|
|
132
|
+
}
|
|
76
133
|
}
|
|
77
134
|
//# sourceMappingURL=allowlist.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../src/credentials/allowlist.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The egress proxy's configuration, checked once when it starts: the allowlist of names and the credential routes. A\n * bad entry throws, so a typo can't widen what leaves the machine. It is pure and portable.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { isAddressLiteral } from \"./addresses.js\";\n\n/** A host the proxy may reach on one port. A `*.` name matches every name under it, and never the name itself. */\nexport interface AllowEntry {\n readonly name: string;\n readonly wildcard: boolean;\n readonly port: number;\n}\n\n/** One credential route: where a request for `/<route>/…` goes, and how the proxy adds the credential. */\nexport interface CredentialRoute {\n /** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */\n readonly route: string;\n /** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */\n readonly host: string;\n /** The methods the route accepts, such as `[\"GET\"]`. A request with another method is refused. */\n readonly methods: readonly string[];\n /** The request header that carries the credential, such as `authorization`. */\n readonly header: string;\n /** The real secret, read at each request so a rotated key is used at once. It never enters the sandbox. */\n readonly secret: () => Promise<string>;\n}\n\n/** A route with its host and port split, its method and header names normalised, and its sentinel. */\nexport interface ParsedRoute {\n readonly route: string;\n readonly hostname: string;\n readonly port: number;\n readonly methods: ReadonlySet<string>;\n readonly header: string;\n readonly secret: () => Promise<string>;\n}\n\nconst HOST_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;\nconst ROUTE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;\nconst HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;\nconst METHOD = /^[A-Z]{3,10}$/;\n// Headers the proxy sets or removes itself, so a route can't name one as its credential header.\nconst RESERVED_HEADERS = new Set([\n \"host\",\n \"content-length\",\n \"transfer-encoding\",\n \"connection\",\n \"keep-alive\",\n \"te\",\n \"trailer\",\n \"upgrade\",\n \"proxy-authorization\",\n \"proxy-authenticate\",\n \"proxy-connection\",\n]);\n\nfunction invalid(message: string): HarnessError {\n return new HarnessError(\"invalid_egress_options\", message);\n}\n\n/** The lower-case host name and the port of `text`, which is `name` or `name:port`, or an error. */\nfunction splitHost(text: string, what: string): { name: string; port: number } {\n const [name = \"\", port, extra] = text.toLowerCase().split(\":\");\n const portNumber = port === undefined ? 443 : Number(port);\n if (extra !== undefined || !Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {\n throw invalid(`${what} ${JSON.stringify(text)} has a bad port`);\n }\n return { name, port: portNumber };\n}\n\n/** Parses the allowlist: each entry is `name`, `*.name`, with `:port` when it isn't 443. */\nexport function parseAllow(entries: readonly string[]): AllowEntry[] {\n return entries.map((entry) => {\n const wildcard = entry.startsWith(\"*.\");\n const { name, port } = splitHost(wildcard ? entry.slice(2) : entry, \"the allowlist entry\");\n if (!HOST_NAME.test(name) || isAddressLiteral(name)) {\n throw invalid(\n `the allowlist entry ${JSON.stringify(entry)} must be a host name, such as example.com or *.example.com`,\n );\n }\n return { name, wildcard, port };\n });\n}\n\n/** Whether `host` on `port` is on the allowlist. `host` is lower case, without a trailing dot. */\nexport function isAllowed(allow: readonly AllowEntry[], host: string, port: number): boolean {\n return allow.some(\n (entry) => entry.port === port && (entry.wildcard ? host.endsWith(`.${entry.name}`) : host === entry.name),\n );\n}\n\n/** Parses and checks the routes, and refuses two with one name. */\nexport function parseRoutes(routes: readonly CredentialRoute[]): ParsedRoute[] {\n const seen = new Set<string>();\n return routes.map((route) => {\n if (!ROUTE_NAME.test(route.route)) throw invalid(`the route name ${JSON.stringify(route.route)} is not usable`);\n if (seen.has(route.route)) throw invalid(`two routes are named ${route.route}`);\n seen.add(route.route);\n const { name, port } = splitHost(route.host, \"the route host\");\n if (!HOST_NAME.test(name) || isAddressLiteral(name))\n throw invalid(`the route host ${route.host} must be a host name`);\n const methods = route.methods.map((method) => method.toUpperCase());\n if (methods.length === 0 || !methods.every((method) => METHOD.test(method)) || methods.includes(\"CONNECT\")) {\n throw invalid(`the route ${route.route} needs a list of methods, such as [\"GET\"]`);\n }\n const header = route.header.toLowerCase();\n if (!HEADER_NAME.test(header) || RESERVED_HEADERS.has(header)) {\n throw invalid(`the route ${route.route} can't carry its credential in the header ${route.header}`);\n }\n if (typeof route.secret !== \"function\") throw invalid(`the route ${route.route} needs a secret function`);\n return { route: route.route, hostname: name, port, methods: new Set(methods), header, secret: route.secret };\n });\n}\n"]}
|
|
1
|
+
{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../src/credentials/allowlist.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The egress proxy's configuration, checked once when it starts: the allowlist of names and the credential routes. A\n * bad entry throws, so a typo can't widen what leaves the machine. It is pure and portable.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { isAddressLiteral } from \"./addresses.js\";\nimport { checkGitFilter, type GitRouteFilter } from \"./git-route.js\";\n\n/** A host the proxy may reach on one port. A `*.` name matches every name under it, and never the name itself. */\nexport interface AllowEntry {\n readonly name: string;\n readonly wildcard: boolean;\n readonly port: number;\n}\n\n/** One credential route: where a request for `/<route>/…` goes, and how the proxy adds the credential. */\nexport interface CredentialRoute {\n /** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */\n readonly route: string;\n /** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */\n readonly host: string;\n /** The methods the route accepts, such as `[\"GET\"]`. A request with another method is refused. */\n readonly methods: readonly string[];\n /** The request header that carries the credential, such as `authorization`. */\n readonly header: string;\n /** The real secret, read at each request so a rotated key is used at once. It never enters the sandbox. */\n readonly secret: () => Promise<string>;\n /**\n * Makes the route a git route: only git's smart HTTP requests for the listed repositories pass, a push only to the\n * listed branches, and the secret goes in HTTP Basic as the password of `username`. Its `header` must be\n * `authorization` and its `methods` `GET` and `POST`. The sandbox's git sends the route's sentinel as its password.\n */\n readonly git?: GitRouteFilter;\n}\n\n/** A route with its host and port split, its method and header names normalised, and its sentinel. */\nexport interface ParsedRoute {\n readonly route: string;\n readonly hostname: string;\n readonly port: number;\n readonly methods: ReadonlySet<string>;\n readonly header: string;\n readonly secret: () => Promise<string>;\n readonly git?: GitRouteFilter;\n}\n\nconst HOST_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;\nconst ROUTE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;\nconst HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;\nconst METHOD = /^[A-Z]{3,10}$/;\n// Headers the proxy sets or removes itself, so a route can't name one as its credential header.\nconst RESERVED_HEADERS = new Set([\n \"host\",\n \"content-length\",\n \"transfer-encoding\",\n \"connection\",\n \"keep-alive\",\n \"te\",\n \"trailer\",\n \"upgrade\",\n \"proxy-authorization\",\n \"proxy-authenticate\",\n \"proxy-connection\",\n]);\n\nfunction invalid(message: string): HarnessError {\n return new HarnessError(\"invalid_egress_options\", message);\n}\n\n/** The lower-case host name and the port of `text`, which is `name` or `name:port`, or an error. */\nfunction splitHost(text: string, what: string): { name: string; port: number } {\n const [name = \"\", port, extra] = text.toLowerCase().split(\":\");\n const portNumber = port === undefined ? 443 : Number(port);\n if (extra !== undefined || !Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {\n throw invalid(`${what} ${JSON.stringify(text)} has a bad port`);\n }\n return { name, port: portNumber };\n}\n\n/** Parses the allowlist: each entry is `name`, `*.name`, with `:port` when it isn't 443. */\nexport function parseAllow(entries: readonly string[]): AllowEntry[] {\n return entries.map((entry) => {\n const wildcard = entry.startsWith(\"*.\");\n const { name, port } = splitHost(wildcard ? entry.slice(2) : entry, \"the allowlist entry\");\n if (!HOST_NAME.test(name) || isAddressLiteral(name)) {\n throw invalid(\n `the allowlist entry ${JSON.stringify(entry)} must be a host name, such as example.com or *.example.com`,\n );\n }\n return { name, wildcard, port };\n });\n}\n\n/** Whether `host` on `port` is on the allowlist. `host` is lower case, without a trailing dot. */\nexport function isAllowed(allow: readonly AllowEntry[], host: string, port: number): boolean {\n return allow.some(\n (entry) => entry.port === port && (entry.wildcard ? host.endsWith(`.${entry.name}`) : host === entry.name),\n );\n}\n\n/** Whether `name` is on the allowlist on any port, so a tunnel could reach it. */\nconst allowedOnAnyPort = (allow: readonly AllowEntry[], name: string): boolean =>\n allow.some((entry) => (entry.wildcard ? name.endsWith(`.${entry.name}`) : name === entry.name));\n\n/**\n * The first git route that shares its host with a way around its filter, and what that way is: an allowlist entry, on\n * any port, that lets a tunnel reach the host, or another route to the same host, which would carry a credential there\n * without the git route's repository and ref checks. Hosts are compared in lower case without their ports.\n */\nexport function gitHostOverlap(\n routes: readonly Pick<CredentialRoute, \"host\" | \"git\">[],\n allow: readonly AllowEntry[],\n): { readonly index: number; readonly with: \"allow\" | \"route\" } | undefined {\n const names = routes.map((route) =>\n String(route.host)\n .toLowerCase()\n .replace(/:[0-9]*$/, \"\"),\n );\n for (const [index, route] of routes.entries()) {\n if (route.git === undefined) continue;\n const name = names[index] ?? \"\";\n if (allowedOnAnyPort(allow, name)) return { index, with: \"allow\" };\n if (names.some((other, at) => at !== index && other === name)) return { index, with: \"route\" };\n }\n return undefined;\n}\n\n/**\n * Parses and checks the routes against the parsed allowlist. It refuses two routes with one name, and a git route whose\n * host is also on the allowlist or is another route's host, because either would go around its filter.\n */\nexport function parseRoutes(routes: readonly CredentialRoute[], allow: readonly AllowEntry[]): ParsedRoute[] {\n const seen = new Set<string>();\n const parsed = routes.map((route) => {\n if (!ROUTE_NAME.test(route.route)) throw invalid(`the route name ${JSON.stringify(route.route)} is not usable`);\n if (seen.has(route.route)) throw invalid(`two routes are named ${route.route}`);\n seen.add(route.route);\n return parseRoute(route);\n });\n const overlap = gitHostOverlap(routes, allow);\n if (overlap !== undefined) {\n const name = routes[overlap.index]?.route ?? \"\";\n throw invalid(\n overlap.with === \"allow\"\n ? `the host of the git route ${name} is also on the allowlist, so a tunnel could go around its filter`\n : `the host of the git route ${name} is another route's host, which could go around its filter`,\n );\n }\n return parsed;\n}\n\n/** Parses and checks one route's host, methods, header, secret and git filter. */\nfunction parseRoute(route: CredentialRoute): ParsedRoute {\n const { name, port } = splitHost(route.host, \"the route host\");\n if (!HOST_NAME.test(name) || isAddressLiteral(name))\n throw invalid(`the route host ${route.host} must be a host name`);\n const methods = route.methods.map((method) => method.toUpperCase());\n if (methods.length === 0 || !methods.every((method) => METHOD.test(method)) || methods.includes(\"CONNECT\")) {\n throw invalid(`the route ${route.route} needs a list of methods, such as [\"GET\"]`);\n }\n const header = route.header.toLowerCase();\n if (!HEADER_NAME.test(header) || RESERVED_HEADERS.has(header)) {\n throw invalid(`the route ${route.route} can't carry its credential in the header ${route.header}`);\n }\n if (typeof route.secret !== \"function\") throw invalid(`the route ${route.route} needs a secret function`);\n if (route.git !== undefined) checkGitRoute(route.git, methods, header);\n return {\n route: route.route,\n hostname: name,\n port,\n methods: new Set(methods),\n header,\n secret: route.secret,\n ...(route.git === undefined ? {} : { git: route.git }),\n };\n}\n\n/** Throws unless a git route carries its credential in `authorization` and takes exactly `GET` and `POST`. */\nfunction checkGitRoute(filter: GitRouteFilter, methods: readonly string[], header: string): void {\n checkGitFilter(filter);\n if (header !== \"authorization\") throw invalid(\"a git route carries its credential in the authorization header\");\n if (new Set(methods).size !== 2 || !methods.includes(\"GET\") || !methods.includes(\"POST\")) {\n throw invalid(\"a git route takes the methods GET and POST\");\n }\n}\n"]}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { type CredentialRoute } from "./allowlist.js";
|
|
2
|
+
/** A route that swaps the sentinel in one request header for a credential, as `startEgressProxy()`'s routes do. */
|
|
3
|
+
export interface HeaderEgressRoute {
|
|
4
|
+
readonly kind: "header";
|
|
5
|
+
/** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */
|
|
6
|
+
readonly route: string;
|
|
7
|
+
/** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */
|
|
8
|
+
readonly host: string;
|
|
9
|
+
/** The methods the route accepts, such as `["GET"]`. */
|
|
10
|
+
readonly methods: readonly string[];
|
|
11
|
+
/** The request header that carries the credential, such as `authorization`. */
|
|
12
|
+
readonly header: string;
|
|
13
|
+
/** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */
|
|
14
|
+
readonly credential: string;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* A route for git over HTTPS: git's smart HTTP requests for the listed repositories only, and a push only to the listed
|
|
18
|
+
* branches. A deletion and a tag are always refused, and so is anything the route can't parse.
|
|
19
|
+
*/
|
|
20
|
+
export interface GitEgressRoute {
|
|
21
|
+
readonly kind: "git";
|
|
22
|
+
/** The first part of the path the sandbox's git remote uses, such as `git`. */
|
|
23
|
+
readonly route: string;
|
|
24
|
+
/** The git host, such as `github.com`. */
|
|
25
|
+
readonly host: string;
|
|
26
|
+
/** The repositories the route reaches, as `owner/name`. */
|
|
27
|
+
readonly repositories: readonly string[];
|
|
28
|
+
/** The branches a push may create or update, such as `refs/heads/agent/*`. Leave it out to refuse every push. */
|
|
29
|
+
readonly pushRefs?: readonly string[];
|
|
30
|
+
/** Whether a fetch or clone may read the repositories. Defaults to `false`. */
|
|
31
|
+
readonly fetch?: boolean;
|
|
32
|
+
/** The user name sent with the credential in HTTP Basic. Defaults to `x-access-token`, which GitHub App tokens use. */
|
|
33
|
+
readonly username?: string;
|
|
34
|
+
/** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */
|
|
35
|
+
readonly credential: string;
|
|
36
|
+
}
|
|
37
|
+
/** One credential route of an `EgressPolicy`. */
|
|
38
|
+
export type EgressRoute = HeaderEgressRoute | GitEgressRoute;
|
|
39
|
+
/** What a sandbox may reach: the hosts it may tunnel to, and the routes that add a credential on its behalf. */
|
|
40
|
+
export interface EgressPolicy {
|
|
41
|
+
/** Exact host names, with `:port` when it isn't 443. A wildcard and an address literal are refused. */
|
|
42
|
+
readonly allow: readonly string[];
|
|
43
|
+
readonly routes: readonly EgressRoute[];
|
|
44
|
+
}
|
|
45
|
+
/** The options of `compileEgressPolicy()`. */
|
|
46
|
+
export interface CompileEgressOptions {
|
|
47
|
+
/** Reads the credential a route names, at each request, on the host. It never runs in the sandbox. */
|
|
48
|
+
readonly secret: (name: string) => Promise<string>;
|
|
49
|
+
}
|
|
50
|
+
/** A compiled policy: the `allow` and `routes` options of `startEgressProxy()`. */
|
|
51
|
+
export interface CompiledEgressPolicy {
|
|
52
|
+
readonly allow: readonly string[];
|
|
53
|
+
readonly routes: readonly CredentialRoute[];
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.
|
|
57
|
+
* Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the
|
|
58
|
+
* message names the entry's place, never its value:
|
|
59
|
+
*
|
|
60
|
+
* - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;
|
|
61
|
+
* - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;
|
|
62
|
+
* - a wildcard or an address literal in `allow` or a route's host;
|
|
63
|
+
* - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route
|
|
64
|
+
* whose host is another route's host, because that route would carry a credential there without the ref filter;
|
|
65
|
+
* - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.
|
|
66
|
+
*
|
|
67
|
+
* The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.
|
|
68
|
+
*/
|
|
69
|
+
export declare function compileEgressPolicy(policy: EgressPolicy, options: CompileEgressOptions): CompiledEgressPolicy;
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a
|
|
3
|
+
* backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`
|
|
4
|
+
* compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.
|
|
5
|
+
*/
|
|
6
|
+
import { HarnessError } from "../errors.js";
|
|
7
|
+
import { isAddressLiteral } from "./addresses.js";
|
|
8
|
+
import { gitHostOverlap, parseAllow, parseRoutes } from "./allowlist.js";
|
|
9
|
+
import { checkGitFilter } from "./git-route.js";
|
|
10
|
+
const CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
|
|
11
|
+
// Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a
|
|
12
|
+
// body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that
|
|
13
|
+
// merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS
|
|
14
|
+
// key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.
|
|
15
|
+
const CREDENTIAL_SHAPED = new RegExp([
|
|
16
|
+
"^gh[pousr]_[A-Za-z0-9]{30,}",
|
|
17
|
+
"^github_pat_[A-Za-z0-9_]{20,}",
|
|
18
|
+
"^xox[abposr]-[A-Za-z0-9-]{10,}",
|
|
19
|
+
"^sk-[A-Za-z0-9_-]{20,}",
|
|
20
|
+
"^sk_(live|test)_[A-Za-z0-9]{20,}",
|
|
21
|
+
"^glpat-[A-Za-z0-9_-]{20,}",
|
|
22
|
+
"^AIza[A-Za-z0-9_-]{30,}",
|
|
23
|
+
"^(AKIA|ASIA)[0-9A-Z]{16}$",
|
|
24
|
+
].join("|"));
|
|
25
|
+
const AUTH_SCHEME = /^(Bearer|Basic) /i;
|
|
26
|
+
// What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,
|
|
27
|
+
// `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.
|
|
28
|
+
const TOKEN_SEPARATOR = /[\s=:@,;"'`]+/;
|
|
29
|
+
/** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */
|
|
30
|
+
const credentialShaped = (text) => AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));
|
|
31
|
+
const HEADER_FIELDS = new Set(["kind", "route", "host", "methods", "header", "credential"]);
|
|
32
|
+
const GIT_FIELDS = new Set(["kind", "route", "host", "repositories", "pushRefs", "fetch", "username", "credential"]);
|
|
33
|
+
const DEFAULT_GIT_USERNAME = "x-access-token";
|
|
34
|
+
const invalid = (message) => new HarnessError("invalid_egress_options", message);
|
|
35
|
+
/** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */
|
|
36
|
+
function strings(value) {
|
|
37
|
+
if (typeof value === "string")
|
|
38
|
+
return [value];
|
|
39
|
+
if (Array.isArray(value))
|
|
40
|
+
return value.flatMap(strings);
|
|
41
|
+
if (typeof value === "object" && value !== null)
|
|
42
|
+
return Object.values(value).flatMap(strings);
|
|
43
|
+
return [];
|
|
44
|
+
}
|
|
45
|
+
/** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */
|
|
46
|
+
function checkHost(entry, where) {
|
|
47
|
+
const text = typeof entry === "string" ? entry : "";
|
|
48
|
+
const name = text.replace(/:[0-9]+$/, "");
|
|
49
|
+
if (text.includes("*") || name.startsWith("[") || isAddressLiteral(name)) {
|
|
50
|
+
throw invalid(`${where} must be an exact host name, not a wildcard or an address`);
|
|
51
|
+
}
|
|
52
|
+
try {
|
|
53
|
+
parseAllow([text]);
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
// The proxy's own message quotes the entry, which this one must not.
|
|
57
|
+
throw invalid(`${where} must be a host name, such as example.com`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Throws unless `route` has only its kind's fields and names its credential. */
|
|
61
|
+
function checkRoute(route, index) {
|
|
62
|
+
if (typeof route !== "object" || route === null)
|
|
63
|
+
throw invalid(`route ${index} is not an object`);
|
|
64
|
+
const kind = route.kind;
|
|
65
|
+
const fields = kind === "header" ? HEADER_FIELDS : kind === "git" ? GIT_FIELDS : undefined;
|
|
66
|
+
if (fields === undefined)
|
|
67
|
+
throw invalid(`route ${index} must have the kind header or git`);
|
|
68
|
+
if (Object.keys(route).some((key) => !fields.has(key))) {
|
|
69
|
+
throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);
|
|
70
|
+
}
|
|
71
|
+
const credential = route.credential;
|
|
72
|
+
if (typeof credential !== "string" || !CREDENTIAL_NAME.test(credential)) {
|
|
73
|
+
throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);
|
|
74
|
+
}
|
|
75
|
+
checkHost(route.host, `the host of route ${index}`);
|
|
76
|
+
const { route: name, methods, pushRefs } = route;
|
|
77
|
+
const listed = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
|
|
78
|
+
if (typeof name !== "string" || (kind === "header" && !listed(methods))) {
|
|
79
|
+
throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);
|
|
80
|
+
}
|
|
81
|
+
if (kind === "git" && pushRefs !== undefined && !listed(pushRefs))
|
|
82
|
+
throw invalid(`route ${index}'s pushRefs is not a list`);
|
|
83
|
+
}
|
|
84
|
+
/** The proxy's filter for a git route, with its defaults filled in. */
|
|
85
|
+
function gitFilter(route) {
|
|
86
|
+
return {
|
|
87
|
+
repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],
|
|
88
|
+
pushRefs: [...(route.pushRefs ?? [])],
|
|
89
|
+
fetch: route.fetch ?? false,
|
|
90
|
+
username: route.username ?? DEFAULT_GIT_USERNAME,
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
/** The local proxy's route for one checked egress route. */
|
|
94
|
+
function toCredentialRoute(route, options) {
|
|
95
|
+
const secret = () => options.secret(route.credential);
|
|
96
|
+
if (route.kind === "header") {
|
|
97
|
+
return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };
|
|
98
|
+
}
|
|
99
|
+
return {
|
|
100
|
+
route: route.route,
|
|
101
|
+
host: route.host,
|
|
102
|
+
methods: ["GET", "POST"],
|
|
103
|
+
header: "authorization",
|
|
104
|
+
secret,
|
|
105
|
+
git: gitFilter(route),
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */
|
|
109
|
+
function checkGitRoutes(routes, allow) {
|
|
110
|
+
const overlap = gitHostOverlap(routes.map((route) => ({ host: route.host, ...(route.kind === "git" ? { git: gitFilter(route) } : {}) })), parseAllow(allow));
|
|
111
|
+
if (overlap?.with === "allow") {
|
|
112
|
+
throw invalid(`the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`);
|
|
113
|
+
}
|
|
114
|
+
if (overlap?.with === "route") {
|
|
115
|
+
throw invalid(`the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`);
|
|
116
|
+
}
|
|
117
|
+
for (const [index, route] of routes.entries()) {
|
|
118
|
+
if (route.kind !== "git")
|
|
119
|
+
continue;
|
|
120
|
+
try {
|
|
121
|
+
checkGitFilter(gitFilter(route));
|
|
122
|
+
}
|
|
123
|
+
catch (error) {
|
|
124
|
+
// The filter's messages name a field and its place, never its value.
|
|
125
|
+
throw invalid(`git route ${index} is not usable: ${error.message}`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.
|
|
131
|
+
* Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the
|
|
132
|
+
* message names the entry's place, never its value:
|
|
133
|
+
*
|
|
134
|
+
* - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;
|
|
135
|
+
* - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;
|
|
136
|
+
* - a wildcard or an address literal in `allow` or a route's host;
|
|
137
|
+
* - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route
|
|
138
|
+
* whose host is another route's host, because that route would carry a credential there without the ref filter;
|
|
139
|
+
* - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.
|
|
140
|
+
*
|
|
141
|
+
* The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.
|
|
142
|
+
*/
|
|
143
|
+
export function compileEgressPolicy(policy, options) {
|
|
144
|
+
if (typeof options?.secret !== "function")
|
|
145
|
+
throw invalid("compileEgressPolicy needs a secret function");
|
|
146
|
+
const { allow, routes } = (policy ?? {});
|
|
147
|
+
if (!Array.isArray(allow) || !Array.isArray(routes))
|
|
148
|
+
throw invalid("an egress policy has an allow and a routes list");
|
|
149
|
+
if (Object.keys(policy).some((key) => key !== "allow" && key !== "routes")) {
|
|
150
|
+
throw invalid("an egress policy has only allow and routes");
|
|
151
|
+
}
|
|
152
|
+
if (strings(policy).some(credentialShaped)) {
|
|
153
|
+
throw invalid("the egress policy holds what looks like a credential; name it in a route's credential instead");
|
|
154
|
+
}
|
|
155
|
+
for (const [index, entry] of allow.entries())
|
|
156
|
+
checkHost(entry, `allow entry ${index}`);
|
|
157
|
+
for (const [index, route] of routes.entries())
|
|
158
|
+
checkRoute(route, index);
|
|
159
|
+
checkGitRoutes(routes, allow);
|
|
160
|
+
const compiled = routes.map((route) => toCredentialRoute(route, options));
|
|
161
|
+
try {
|
|
162
|
+
parseRoutes(compiled, parseAllow(allow));
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
// The proxy's own message quotes the route's name or header, which this one must not.
|
|
166
|
+
throw invalid("a route's name, methods or header is not usable, or two routes share a name");
|
|
167
|
+
}
|
|
168
|
+
return { allow: [...allow], routes: compiled };
|
|
169
|
+
}
|
|
170
|
+
//# sourceMappingURL=egress-policy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"egress-policy.js","sourceRoot":"","sources":["../../src/credentials/egress-policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a\n * backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`\n * compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { isAddressLiteral } from \"./addresses.js\";\nimport { type CredentialRoute, gitHostOverlap, parseAllow, parseRoutes } from \"./allowlist.js\";\nimport { checkGitFilter, type GitRouteFilter } from \"./git-route.js\";\n\n/** A route that swaps the sentinel in one request header for a credential, as `startEgressProxy()`'s routes do. */\nexport interface HeaderEgressRoute {\n readonly kind: \"header\";\n /** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */\n readonly route: string;\n /** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */\n readonly host: string;\n /** The methods the route accepts, such as `[\"GET\"]`. */\n readonly methods: readonly string[];\n /** The request header that carries the credential, such as `authorization`. */\n readonly header: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/**\n * A route for git over HTTPS: git's smart HTTP requests for the listed repositories only, and a push only to the listed\n * branches. A deletion and a tag are always refused, and so is anything the route can't parse.\n */\nexport interface GitEgressRoute {\n readonly kind: \"git\";\n /** The first part of the path the sandbox's git remote uses, such as `git`. */\n readonly route: string;\n /** The git host, such as `github.com`. */\n readonly host: string;\n /** The repositories the route reaches, as `owner/name`. */\n readonly repositories: readonly string[];\n /** The branches a push may create or update, such as `refs/heads/agent/*`. Leave it out to refuse every push. */\n readonly pushRefs?: readonly string[];\n /** Whether a fetch or clone may read the repositories. Defaults to `false`. */\n readonly fetch?: boolean;\n /** The user name sent with the credential in HTTP Basic. Defaults to `x-access-token`, which GitHub App tokens use. */\n readonly username?: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/** One credential route of an `EgressPolicy`. */\nexport type EgressRoute = HeaderEgressRoute | GitEgressRoute;\n\n/** What a sandbox may reach: the hosts it may tunnel to, and the routes that add a credential on its behalf. */\nexport interface EgressPolicy {\n /** Exact host names, with `:port` when it isn't 443. A wildcard and an address literal are refused. */\n readonly allow: readonly string[];\n readonly routes: readonly EgressRoute[];\n}\n\n/** The options of `compileEgressPolicy()`. */\nexport interface CompileEgressOptions {\n /** Reads the credential a route names, at each request, on the host. It never runs in the sandbox. */\n readonly secret: (name: string) => Promise<string>;\n}\n\n/** A compiled policy: the `allow` and `routes` options of `startEgressProxy()`. */\nexport interface CompiledEgressPolicy {\n readonly allow: readonly string[];\n readonly routes: readonly CredentialRoute[];\n}\n\nconst CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;\n// Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a\n// body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that\n// merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS\n// key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.\nconst CREDENTIAL_SHAPED = new RegExp(\n [\n \"^gh[pousr]_[A-Za-z0-9]{30,}\",\n \"^github_pat_[A-Za-z0-9_]{20,}\",\n \"^xox[abposr]-[A-Za-z0-9-]{10,}\",\n \"^sk-[A-Za-z0-9_-]{20,}\",\n \"^sk_(live|test)_[A-Za-z0-9]{20,}\",\n \"^glpat-[A-Za-z0-9_-]{20,}\",\n \"^AIza[A-Za-z0-9_-]{30,}\",\n \"^(AKIA|ASIA)[0-9A-Z]{16}$\",\n ].join(\"|\"),\n);\nconst AUTH_SCHEME = /^(Bearer|Basic) /i;\n// What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,\n// `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.\nconst TOKEN_SEPARATOR = /[\\s=:@,;\"'`]+/;\n\n/** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */\nconst credentialShaped = (text: string): boolean =>\n AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));\nconst HEADER_FIELDS = new Set([\"kind\", \"route\", \"host\", \"methods\", \"header\", \"credential\"]);\nconst GIT_FIELDS = new Set([\"kind\", \"route\", \"host\", \"repositories\", \"pushRefs\", \"fetch\", \"username\", \"credential\"]);\nconst DEFAULT_GIT_USERNAME = \"x-access-token\";\n\nconst invalid = (message: string) => new HarnessError(\"invalid_egress_options\", message);\n\n/** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */\nfunction strings(value: unknown): string[] {\n if (typeof value === \"string\") return [value];\n if (Array.isArray(value)) return value.flatMap(strings);\n if (typeof value === \"object\" && value !== null) return Object.values(value).flatMap(strings);\n return [];\n}\n\n/** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */\nfunction checkHost(entry: unknown, where: string): void {\n const text = typeof entry === \"string\" ? entry : \"\";\n const name = text.replace(/:[0-9]+$/, \"\");\n if (text.includes(\"*\") || name.startsWith(\"[\") || isAddressLiteral(name)) {\n throw invalid(`${where} must be an exact host name, not a wildcard or an address`);\n }\n try {\n parseAllow([text]);\n } catch {\n // The proxy's own message quotes the entry, which this one must not.\n throw invalid(`${where} must be a host name, such as example.com`);\n }\n}\n\n/** Throws unless `route` has only its kind's fields and names its credential. */\nfunction checkRoute(route: unknown, index: number): asserts route is EgressRoute {\n if (typeof route !== \"object\" || route === null) throw invalid(`route ${index} is not an object`);\n const kind = (route as { kind?: unknown }).kind;\n const fields = kind === \"header\" ? HEADER_FIELDS : kind === \"git\" ? GIT_FIELDS : undefined;\n if (fields === undefined) throw invalid(`route ${index} must have the kind header or git`);\n if (Object.keys(route).some((key) => !fields.has(key))) {\n throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);\n }\n const credential = (route as { credential?: unknown }).credential;\n if (typeof credential !== \"string\" || !CREDENTIAL_NAME.test(credential)) {\n throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);\n }\n checkHost((route as { host?: unknown }).host, `the host of route ${index}`);\n const { route: name, methods, pushRefs } = route as { route?: unknown; methods?: unknown; pushRefs?: unknown };\n const listed = (value: unknown) => Array.isArray(value) && value.every((item) => typeof item === \"string\");\n if (typeof name !== \"string\" || (kind === \"header\" && !listed(methods))) {\n throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);\n }\n if (kind === \"git\" && pushRefs !== undefined && !listed(pushRefs))\n throw invalid(`route ${index}'s pushRefs is not a list`);\n}\n\n/** The proxy's filter for a git route, with its defaults filled in. */\nfunction gitFilter(route: GitEgressRoute): GitRouteFilter {\n return {\n repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],\n pushRefs: [...(route.pushRefs ?? [])],\n fetch: route.fetch ?? false,\n username: route.username ?? DEFAULT_GIT_USERNAME,\n };\n}\n\n/** The local proxy's route for one checked egress route. */\nfunction toCredentialRoute(route: EgressRoute, options: CompileEgressOptions): CredentialRoute {\n const secret = () => options.secret(route.credential);\n if (route.kind === \"header\") {\n return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };\n }\n return {\n route: route.route,\n host: route.host,\n methods: [\"GET\", \"POST\"],\n header: \"authorization\",\n secret,\n git: gitFilter(route),\n };\n}\n\n/** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */\nfunction checkGitRoutes(routes: readonly EgressRoute[], allow: readonly string[]): void {\n const overlap = gitHostOverlap(\n routes.map((route) => ({ host: route.host, ...(route.kind === \"git\" ? { git: gitFilter(route) } : {}) })),\n parseAllow(allow),\n );\n if (overlap?.with === \"allow\") {\n throw invalid(\n `the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`,\n );\n }\n if (overlap?.with === \"route\") {\n throw invalid(\n `the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`,\n );\n }\n for (const [index, route] of routes.entries()) {\n if (route.kind !== \"git\") continue;\n try {\n checkGitFilter(gitFilter(route));\n } catch (error) {\n // The filter's messages name a field and its place, never its value.\n throw invalid(`git route ${index} is not usable: ${(error as Error).message}`);\n }\n }\n}\n\n/**\n * Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.\n * Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the\n * message names the entry's place, never its value:\n *\n * - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;\n * - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;\n * - a wildcard or an address literal in `allow` or a route's host;\n * - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route\n * whose host is another route's host, because that route would carry a credential there without the ref filter;\n * - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.\n *\n * The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.\n */\nexport function compileEgressPolicy(policy: EgressPolicy, options: CompileEgressOptions): CompiledEgressPolicy {\n if (typeof options?.secret !== \"function\") throw invalid(\"compileEgressPolicy needs a secret function\");\n const { allow, routes } = (policy ?? {}) as Partial<EgressPolicy>;\n if (!Array.isArray(allow) || !Array.isArray(routes)) throw invalid(\"an egress policy has an allow and a routes list\");\n if (Object.keys(policy).some((key) => key !== \"allow\" && key !== \"routes\")) {\n throw invalid(\"an egress policy has only allow and routes\");\n }\n if (strings(policy).some(credentialShaped)) {\n throw invalid(\"the egress policy holds what looks like a credential; name it in a route's credential instead\");\n }\n for (const [index, entry] of allow.entries()) checkHost(entry, `allow entry ${index}`);\n for (const [index, route] of routes.entries()) checkRoute(route, index);\n checkGitRoutes(routes, allow);\n const compiled = routes.map((route) => toCredentialRoute(route, options));\n try {\n parseRoutes(compiled, parseAllow(allow));\n } catch {\n // The proxy's own message quotes the route's name or header, which this one must not.\n throw invalid(\"a route's name, methods or header is not usable, or two routes share a name\");\n }\n return { allow: [...allow], routes: compiled };\n}\n"]}
|
|
@@ -38,8 +38,20 @@ export interface EgressProxyOptions {
|
|
|
38
38
|
* for a real run: the check is what keeps a name that points at the host's own network from being reached.
|
|
39
39
|
*/
|
|
40
40
|
readonly unsafeAllowAddresses?: readonly string[];
|
|
41
|
-
/**
|
|
41
|
+
/**
|
|
42
|
+
* Ends a tunnel, a forwarded request or a push check that is idle this long. A whole number of milliseconds from 0 to
|
|
43
|
+
* 2,147,483,647, where 0 turns the idle timeout off, as it does for a socket; anything else throws
|
|
44
|
+
* `invalid_egress_options` when the proxy starts. Defaults to 120000.
|
|
45
|
+
*/
|
|
42
46
|
readonly idleTimeoutMs?: number;
|
|
47
|
+
/**
|
|
48
|
+
* The longest a push's command list may take to arrive, from the start of its body, however often bytes come. The
|
|
49
|
+
* clock starts once and is never reset, so a client that sends a byte just inside the idle timeout is still cut off;
|
|
50
|
+
* a push that takes longer is refused with `git_timeout`. Only the command list is timed, not the pack after it. A
|
|
51
|
+
* whole number of milliseconds from 1 to 2,147,483,647; anything else throws `invalid_egress_options` when the proxy
|
|
52
|
+
* starts. Defaults to 60000.
|
|
53
|
+
*/
|
|
54
|
+
readonly pushCheckTimeoutMs?: number;
|
|
43
55
|
}
|
|
44
56
|
/** A running egress proxy. */
|
|
45
57
|
export interface EgressProxy {
|