@cloudsnorkel/cdk-github-runners 0.9.1 → 0.9.2

package/API.md

@@ -4550,6 +4550,68 @@ VPC where builder instances will be launched.
 
 ---
 
+### ApiGatewayAccessProps <a name="ApiGatewayAccessProps" id="@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps"></a>
+
+#### Initializer <a name="Initializer" id="@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.Initializer"></a>
+
+```typescript
+import { ApiGatewayAccessProps } from '@cloudsnorkel/cdk-github-runners'
+
+const apiGatewayAccessProps: ApiGatewayAccessProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedIps">allowedIps</a></code> | <code>string[]</code> | List of IP addresses in CIDR notation that are allowed to access the API Gateway. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedSecurityGroups">allowedSecurityGroups</a></code> | <code>aws-cdk-lib.aws_ec2.ISecurityGroup[]</code> | List of security groups that are allowed to access the API Gateway. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedVpc">allowedVpc</a></code> | <code>aws-cdk-lib.aws_ec2.IVpc</code> | Creates a private API Gateway and allows access from the specified VPC. |
+
+---
+
+##### `allowedIps`<sup>Optional</sup> <a name="allowedIps" id="@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedIps"></a>
+
+```typescript
+public readonly allowedIps: string[];
+```
+
+- *Type:* string[]
+
+List of IP addresses in CIDR notation that are allowed to access the API Gateway.
+
+If not specified on public API Gateway, all IP addresses are allowed.
+
+If not specified on private API Gateway, no IP addresses are allowed (but specified security groups are).
+
+---
+
+##### `allowedSecurityGroups`<sup>Optional</sup> <a name="allowedSecurityGroups" id="@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedSecurityGroups"></a>
+
+```typescript
+public readonly allowedSecurityGroups: ISecurityGroup[];
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[]
+
+List of security groups that are allowed to access the API Gateway.
+
+Only works for private API Gateways with {@link allowedVpc}.
+
+---
+
+##### `allowedVpc`<sup>Optional</sup> <a name="allowedVpc" id="@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps.property.allowedVpc"></a>
+
+```typescript
+public readonly allowedVpc: IVpc;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.IVpc
+
+Creates a private API Gateway and allows access from the specified VPC.
+
+---
+
 ### AwsImageBuilderRunnerImageBuilderProps <a name="AwsImageBuilderRunnerImageBuilderProps" id="@cloudsnorkel/cdk-github-runners.AwsImageBuilderRunnerImageBuilderProps"></a>
 
 #### Initializer <a name="Initializer" id="@cloudsnorkel/cdk-github-runners.AwsImageBuilderRunnerImageBuilderProps.Initializer"></a>
@@ -5819,8 +5881,11 @@ const gitHubRunnersProps: GitHubRunnersProps = { ... }
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.logOptions">logOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.LogOptions">LogOptions</a></code> | Logging options for the state machine that manages the runners. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]</code> | List of runner providers to use. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.securityGroup">securityGroup</a></code> | <code>aws-cdk-lib.aws_ec2.ISecurityGroup</code> | Security group attached to all management functions. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.setupAccess">setupAccess</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a></code> | Access configuration for the setup function. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.statusAccess">statusAccess</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a></code> | Access configuration for the status function. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.vpc">vpc</a></code> | <code>aws-cdk-lib.aws_ec2.IVpc</code> | VPC used for all management functions. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.vpcSubnets">vpcSubnets</a></code> | <code>aws-cdk-lib.aws_ec2.SubnetSelection</code> | VPC subnets used for all management functions. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.webhookAccess">webhookAccess</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a></code> | Access configuration for the webhook function. |
 
 ---
 
@@ -5928,6 +5993,36 @@ Use this with to provide access to GitHub Enterprise Server hosted inside a VPC.
 
 ---
 
+##### `setupAccess`<sup>Optional</sup> <a name="setupAccess" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.setupAccess"></a>
+
+```typescript
+public readonly setupAccess: LambdaAccess;
+```
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a>
+- *Default:* LambdaAccess.lambdaUrl()
+
+Access configuration for the setup function.
+
+Once you finish the setup process, you can set this to `LambdaAccess.noAccess()` to remove access to the setup function. You can also use `LambdaAccess.apiGateway({ allowedIps: ['my-ip/0']})` to limit access to your IP only.
+
+---
+
+##### `statusAccess`<sup>Optional</sup> <a name="statusAccess" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.statusAccess"></a>
+
+```typescript
+public readonly statusAccess: LambdaAccess;
+```
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a>
+- *Default:* LambdaAccess.noAccess()
+
+Access configuration for the status function.
+
+This function returns a lot of sensitive information about the runner, so you should only allow access to it from trusted IPs, if at all.
+
+---
+
 ##### `vpc`<sup>Optional</sup> <a name="vpc" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.vpc"></a>
 
 ```typescript
@@ -5956,6 +6051,25 @@ Use this with GitHub Enterprise Server hosted that's inaccessible from outside t
 
 ---
 
+##### `webhookAccess`<sup>Optional</sup> <a name="webhookAccess" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.webhookAccess"></a>
+
+```typescript
+public readonly webhookAccess: LambdaAccess;
+```
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess">LambdaAccess</a>
+- *Default:* LambdaAccess.lambdaUrl()
+
+Access configuration for the webhook function.
+
+This function is called by GitHub when a new workflow job is scheduled. For an extra layer of security, you can set this to `LambdaAccess.apiGateway({ allowedIps: LambdaAccess.githubWebhookIps() })`.
+
+You can also set this to `LambdaAccess.privateApiGateway()` if your GitHub Enterprise Server is hosted in a VPC. This will create an API Gateway endpoint that's only accessible from within the VPC.
+
+*WARNING*: changing access type may change the URL. When the URL changes, you must update GitHub as well.
+
+---
+
 ### ImageBuilderAsset <a name="ImageBuilderAsset" id="@cloudsnorkel/cdk-github-runners.ImageBuilderAsset"></a>
 
 An asset including file or directory to place inside the built image.
@@ -7262,6 +7376,107 @@ X86_64.
 
 ---
 
+### LambdaAccess <a name="LambdaAccess" id="@cloudsnorkel/cdk-github-runners.LambdaAccess"></a>
+
+Access configuration options for Lambda functions like setup and webhook function.
+
+Use this to limit access to these functions.
+
+#### Initializers <a name="Initializers" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.Initializer"></a>
+
+```typescript
+import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners'
+
+new LambdaAccess()
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess.apiGateway">apiGateway</a></code> | Provide access using API Gateway. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess.githubWebhookIps">githubWebhookIps</a></code> | Downloads the list of IP addresses used by GitHub.com for webhooks. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess.lambdaUrl">lambdaUrl</a></code> | Provide access using Lambda URL. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess.noAccess">noAccess</a></code> | Disables access to the configured Lambda function. |
+
+---
+
+##### `apiGateway` <a name="apiGateway" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.apiGateway"></a>
+
+```typescript
+import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners'
+
+LambdaAccess.apiGateway(props?: ApiGatewayAccessProps)
+```
+
+Provide access using API Gateway.
+
+This is the most secure option, but requires additional configuration. It allows you to limit access to specific IP addresses and even to a specific VPC.
+
+To limit access to GitHub.com use:
+
+```
+LambdaAccess.apiGateway({
+  allowedIps: LambdaAccess.githubWebhookIps(),
+});
+```
+
+Alternatively, get and manually update the list manually with:
+
+```
+curl https://api.github.com/meta | jq .hooks
+```
+
+###### `props`<sup>Optional</sup> <a name="props" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.apiGateway.parameter.props"></a>
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps">ApiGatewayAccessProps</a>
+
+---
+
+##### `githubWebhookIps` <a name="githubWebhookIps" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.githubWebhookIps"></a>
+
+```typescript
+import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners'
+
+LambdaAccess.githubWebhookIps()
+```
+
+Downloads the list of IP addresses used by GitHub.com for webhooks.
+
+Note that downloading dynamic data during deployment is not recommended in CDK. This is a workaround for the lack of a better solution.
+
+##### `lambdaUrl` <a name="lambdaUrl" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.lambdaUrl"></a>
+
+```typescript
+import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners'
+
+LambdaAccess.lambdaUrl()
+```
+
+Provide access using Lambda URL.
+
+This is the default and simplest option. It puts no limits on the requester, but the Lambda functions themselves authenticate every request.
+
+##### `noAccess` <a name="noAccess" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.noAccess"></a>
+
+```typescript
+import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners'
+
+LambdaAccess.noAccess()
+```
+
+Disables access to the configured Lambda function.
+
+This is useful for the setup function after setup is done.
+
+
+
 ### LinuxUbuntuComponents <a name="LinuxUbuntuComponents" id="@cloudsnorkel/cdk-github-runners.LinuxUbuntuComponents"></a>
 
 Components for Ubuntu Linux that can be used with AWS Image Builder based builders.

package/assets/lambdas/setup.lambda/index.js

@@ -9164,7 +9164,8 @@ function response(code, body) {
   };
 }
 async function handleRoot(event, setupToken) {
-  const setupBaseUrl = `https://${event.requestContext.domainName}`;
+  const stage = event.requestContext.stage == "$default" ? "" : `/${event.requestContext.stage}`;
+  const setupBaseUrl = `https://${event.requestContext.domainName}${stage}`;
   const githubSecrets = await getSecretJsonValue(process.env.GITHUB_SECRET_ARN);
   return response(200, getHtml(setupBaseUrl, setupToken, githubSecrets.domain));
 }
@@ -9254,20 +9255,23 @@ exports.handler = async function(event) {
     return response(403, "Wrong setup token.");
   }
   try {
-    if (event.requestContext.http.path == "/") {
+    const path = event.path ?? event.rawPath;
+    const method = event.httpMethod ?? event.requestContext.http.method;
+    if (path == "/") {
       return await handleRoot(event, setupToken);
-    } else if (event.requestContext.http.path == "/domain" && event.requestContext.http.method == "POST") {
+    } else if (path == "/domain" && method == "POST") {
       return await handleDomain(event);
-    } else if (event.requestContext.http.path == "/pat" && event.requestContext.http.method == "POST") {
+    } else if (path == "/pat" && method == "POST") {
       return await handlePat(event);
-    } else if (event.requestContext.http.path == "/complete-new-app" && event.requestContext.http.method == "GET") {
+    } else if (path == "/complete-new-app" && method == "GET") {
       return await handleNewApp(event);
-    } else if (event.requestContext.http.path == "/app" && event.requestContext.http.method == "POST") {
+    } else if (path == "/app" && method == "POST") {
       return await handleExistingApp(event);
     } else {
       return response(404, "Not found");
     }
   } catch (e) {
+    console.error(e);
     return response(500, `<b>Error:</b> ${e}`);
   }
 };

package/assets/lambdas/status.lambda/index.js

@@ -21184,7 +21184,19 @@ async function generateProvidersStatus(stack, logicalId) {
     return p;
   }));
 }
-exports.handler = async function() {
+function safeReturnValue(event, status) {
+  if (event.path) {
+    return {
+      statusCode: 200,
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(status)
+    };
+  }
+  return status;
+}
+exports.handler = async function(event) {
   if (!process.env.WEBHOOK_SECRET_ARN || !process.env.GITHUB_SECRET_ARN || !process.env.GITHUB_PRIVATE_KEY_SECRET_ARN || !process.env.LOGICAL_ID || !process.env.WEBHOOK_HANDLER_ARN || !process.env.STEP_FUNCTION_ARN || !process.env.SETUP_SECRET_ARN || !process.env.SETUP_FUNCTION_URL || !process.env.STACK_NAME) {
     throw new Error("Missing environment variables");
   }
@@ -21261,14 +21273,14 @@ exports.handler = async function() {
     githubSecrets = await getSecretJsonValue(process.env.GITHUB_SECRET_ARN);
   } catch (e) {
     status.github.auth.status = `Unable to read secret: ${e}`;
-    return status;
+    return safeReturnValue(event, status);
   }
   let privateKey;
   try {
     privateKey = await getSecretValue(process.env.GITHUB_PRIVATE_KEY_SECRET_ARN);
   } catch (e) {
     status.github.auth.status = `Unable to read private key secret: ${e}`;
-    return status;
+    return safeReturnValue(event, status);
   }
   let baseUrl = baseUrlFromDomain(githubSecrets.domain);
   status.github.domain = githubSecrets.domain;
@@ -21280,14 +21292,14 @@ exports.handler = async function() {
       octokit = new import_core.Octokit({ baseUrl, auth: githubSecrets.personalAuthToken });
     } catch (e) {
       status.github.auth.status = `Unable to authenticate using personal auth token: ${e}`;
-      return status;
+      return safeReturnValue(event, status);
     }
     try {
       const user = await octokit.request("GET /user");
       status.github.auth.personalAuthToken = `username: ${user.data.login}`;
     } catch (e) {
       status.github.auth.status = `Unable to call /user with personal auth token: ${e}`;
-      return status;
+      return safeReturnValue(event, status);
     }
     status.github.auth.status = "OK";
     status.github.webhook.status = "Unable to verify automatically";
@@ -21306,14 +21318,14 @@ exports.handler = async function() {
       });
     } catch (e) {
       status.github.auth.status = `Unable to authenticate app: ${e}`;
-      return status;
+      return safeReturnValue(event, status);
     }
     try {
       const app = (await appOctokit.request("GET /app")).data;
       status.github.auth.app.url = app.html_url;
     } catch (e) {
       status.github.auth.status = `Unable to get app details: ${e}`;
-      return status;
+      return safeReturnValue(event, status);
     }
     try {
       const installations = (await appOctokit.request("GET /app/installations")).data;
@@ -21355,7 +21367,7 @@ exports.handler = async function() {
       }
     } catch (e) {
       status.github.auth.status = "Unable to list app installations";
-      return status;
+      return safeReturnValue(event, status);
     }
     status.github.auth.status = "OK";
     try {
@@ -21367,10 +21379,10 @@ exports.handler = async function() {
       }
     } catch (e) {
       status.github.webhook.status = `Unable to check app configuration: ${e}`;
-      return status;
+      return safeReturnValue(event, status);
     }
   }
-  return status;
+  return safeReturnValue(event, status);
 };
 /*! Bundled license information:
 

package/assets/lambdas/webhook-handler.lambda/index.js

@@ -45,8 +45,16 @@ async function getSecretJsonValue(arn) {
 
 // src/lambdas/webhook-handler.lambda.ts
 var sf = new AWS2.StepFunctions();
+function getHeader(event, header) {
+  for (const headerName of Object.keys(event.headers)) {
+    if (headerName.toLowerCase() === header.toLowerCase()) {
+      return event.headers[headerName];
+    }
+  }
+  return void 0;
+}
 function verifyBody(event, secret) {
-  const sig = Buffer.from(event.headers["x-hub-signature-256"] || "", "utf8");
+  const sig = Buffer.from(getHeader(event, "x-hub-signature-256") || "", "utf8");
   if (!event.body) {
     throw new Error("No body");
   }
@@ -81,21 +89,21 @@ exports.handler = async function(event) {
       body: "Bad signature"
     };
   }
-  if (event.headers["content-type"] !== "application/json") {
-    console.error(`This webhook only accepts JSON payloads, got ${event.headers["content-type"]}`);
+  if (getHeader(event, "content-type") !== "application/json") {
+    console.error(`This webhook only accepts JSON payloads, got ${getHeader(event, "content-type")}`);
     return {
       statusCode: 400,
       body: "Expecting JSON payload"
     };
   }
-  if (event.headers["x-github-event"] === "ping") {
+  if (getHeader(event, "x-github-event") === "ping") {
     return {
       statusCode: 200,
       body: "Pong"
     };
   }
-  if (event.headers["x-github-event"] !== "workflow_job") {
-    console.error(`This webhook only accepts workflow_job, got ${event.headers["x-github-event"]}`);
+  if (getHeader(event, "x-github-event") !== "workflow_job") {
+    console.error(`This webhook only accepts workflow_job, got ${getHeader(event, "x-github-event")}`);
     return {
       statusCode: 400,
       body: "Expecting workflow_job"
@@ -118,7 +126,7 @@ exports.handler = async function(event) {
   }
   let labels = {};
   payload.workflow_job.labels.forEach((l) => labels[l.toLowerCase()] = true);
-  let executionName = `${payload.repository.full_name.replace("/", "-")}-${event.headers["x-github-delivery"]}`.slice(0, 64);
+  let executionName = `${payload.repository.full_name.replace("/", "-")}-${getHeader(event, "x-github-delivery")}`.slice(0, 64);
   const execution = await sf.startExecution({
     stateMachineArn: process.env.STEP_FUNCTION_ARN,
     input: JSON.stringify({

package/lib/access.d.ts

@@ -0,0 +1,65 @@
+import { aws_ec2 as ec2, aws_lambda as lambda } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+export interface ApiGatewayAccessProps {
+    /**
+     * List of IP addresses in CIDR notation that are allowed to access the API Gateway.
+     *
+     * If not specified on public API Gateway, all IP addresses are allowed.
+     *
+     * If not specified on private API Gateway, no IP addresses are allowed (but specified security groups are).
+     */
+    readonly allowedIps?: string[];
+    /**
+     * Creates a private API Gateway and allows access from the specified VPC.
+     */
+    readonly allowedVpc?: ec2.IVpc;
+    /**
+     * List of security groups that are allowed to access the API Gateway.
+     *
+     * Only works for private API Gateways with {@link allowedVpc}.
+     */
+    readonly allowedSecurityGroups?: ec2.ISecurityGroup[];
+}
+/**
+ * Access configuration options for Lambda functions like setup and webhook function. Use this to limit access to these functions.
+ */
+export declare abstract class LambdaAccess {
+    /**
+     * Disables access to the configured Lambda function. This is useful for the setup function after setup is done.
+     */
+    static noAccess(): LambdaAccess;
+    /**
+     * Provide access using Lambda URL. This is the default and simplest option. It puts no limits on the requester, but the Lambda functions themselves authenticate every request.
+     */
+    static lambdaUrl(): LambdaAccess;
+    /**
+     * Provide access using API Gateway. This is the most secure option, but requires additional configuration. It allows you to limit access to specific IP addresses and even to a specific VPC.
+     *
+     * To limit access to GitHub.com use:
+     *
+     * ```
+     * LambdaAccess.apiGateway({
+     *   allowedIps: LambdaAccess.githubWebhookIps(),
+     * });
+     * ```
+     *
+     * Alternatively, get and manually update the list manually with:
+     *
+     * ```
+     * curl https://api.github.com/meta | jq .hooks
+     * ```
+     */
+    static apiGateway(props?: ApiGatewayAccessProps): LambdaAccess;
+    /**
+     * Downloads the list of IP addresses used by GitHub.com for webhooks.
+     *
+     * Note that downloading dynamic data during deployment is not recommended in CDK. This is a workaround for the lack of a better solution.
+     */
+    static githubWebhookIps(): string[];
+    /**
+     * Creates all required resources and returns access URL or empty string if disabled.
+     *
+     * @internal
+     */
+    abstract _bind(construct: Construct, id: string, lambdaFunction: lambda.Function): string;
+}