Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

update docs, add script to notarize

Justin D'Souzafa42de613bbc
diff --git a/docs/docs.json b/docs/docs.json
index daea8047..fb4f1974 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -94,7 +94,14 @@
"group": "Manage Asymptote",
"icon": "sliders",
"pages": [
- "manage/onboarding",
+ {
+ "group": "Onboarding",
+ "root": "manage/onboarding",
+ "pages": [
+ "manage/configure-s3-data-connector",
+ "manage/connect-okta"
+ ]
+ },
{
"group": "Inventory",
"root": "guides/inventory",
diff --git a/docs/manage/configure-s3-data-connector.mdx b/docs/manage/configure-s3-data-connector.mdx
new file mode 100644
index 00000000..aed64e3c
--- /dev/null
+++ b/docs/manage/configure-s3-data-connector.mdx
@@ -0,0 +1,131 @@
+---
+title: "Configure S3 Data Connector"
+description: "Configure read-only S3 access for Asymptote ingestion."
+tag: "Enterprise"
+---
+
+## Overview
+
+Asymptote can ingest customer-hosted event files from a private AWS S3 bucket or prefix. Grant Asymptote's ingestion worker read-only access to the bucket that contains the event files.
+
+Do not make the bucket public. Do not grant write or delete permissions.
+
+At the end of setup, send Asymptote the full IAM role ARN for the role you create.
+
+## Customer Steps
+
+1. Send Asymptote the S3 location details.
+
+ Include:
+
+ - AWS account ID
+ - S3 bucket name
+ - AWS region
+ - Prefix/path for the event files, such as `s3://your-bucket/asymptote/events/`
+ - File format, ideally JSONL or JSONEachRow
+ - Delivery cadence and approximate event volume
+ - Encryption type, either SSE-S3 or SSE-KMS
+ - KMS key ARN, only if SSE-KMS is enabled
+
+2. Create a dedicated IAM role in AWS.
+
+ Sign in to the AWS account that owns the S3 bucket with an IAM user that can create and manage IAM roles. Open the IAM service console, then create a new role named something like `asymptote-s3-read`.
+
+3. Configure the role trust policy.
+
+ Use the IAM ARN Asymptote gives you as the trusted principal. Replace `ASYMPTOTE_IAM_ARN` with that ARN.
+
+ ```json title="IAM role trust policy"
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Principal": {
+ "AWS": "ASYMPTOTE_IAM_ARN"
+ },
+ "Action": "sts:AssumeRole"
+ }
+ ]
+ }
+ ```
+
+4. Attach a read-only S3 policy.
+
+ ```json title="Read-only S3 policy"
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:GetBucketLocation",
+ "s3:ListBucket"
+ ],
+ "Resource": [
+ "arn:aws:s3:::YOUR_BUCKET_NAME"
+ ]
+ },
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:Get*",
+ "s3:List*"
+ ],
+ "Resource": [
+ "arn:aws:s3:::YOUR_BUCKET_NAME/*"
+ ]
+ }
+ ]
+ }
+ ```
+
+ Replace `YOUR_BUCKET_NAME` with the name of the S3 bucket that contains the event files.
+
+5. Add KMS decrypt permission if needed.
+
+ If the bucket uses SSE-KMS, add this statement to the role policy:
+
+ ```json title="SSE-KMS decrypt statement"
+ {
+ "Sid": "DecryptEventObjects",
+ "Effect": "Allow",
+ "Action": "kms:Decrypt",
+ "Resource": "YOUR_KMS_KEY_ARN"
+ }
+ ```
+
+ The KMS key policy must also allow this IAM role to use `kms:Decrypt`.
+
+6. Send Asymptote the final onboarding details.
+
+ Send:
+
+ - IAM role ARN for the role you created
+ - S3 URL/prefix
+ - AWS region
+ - KMS key ARN, if applicable
+ - A small sample event file or example JSONL row
+
+## Event File Requirements
+
+Use newline-delimited JSON, with one complete JSON object per line. Each event should include a UTC-compatible timestamp and stable fields for user, host, repository, branch, agent runtime, event action, and event category when available.
+
+Share a representative sample file before production ingestion. The sample should show realistic field names and value shapes, but should not include secrets.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Asymptote Managed" icon="cloud" href="/deployment/managed">
+ Review managed visibility, governance, and investigation workflows.
+ </Card>
+ <Card title="Endpoint Event Schema" icon="code" href="/telemetry-schema/event-schema">
+ Review normalized event fields and example payloads.
+ </Card>
+ <Card title="AWS S3 Forwarding" icon="bucket" href="/log-forwarding/s3">
+ Configure customer-managed Beacon event forwarding into S3.
+ </Card>
+ <Card title="Data Inventory" icon="table-list" href="/security/data-inventory">
+ Review the endpoint event fields Beacon can write.
+ </Card>
+</Columns>
diff --git a/docs/manage/connect-okta.mdx b/docs/manage/connect-okta.mdx
new file mode 100644
index 00000000..3ed69f2e
--- /dev/null
+++ b/docs/manage/connect-okta.mdx
@@ -0,0 +1,31 @@
+---
+title: "Connect Okta"
+description: "Connect Okta to populate identity and device inventory in Asymptote."
+tag: "Enterprise"
+---
+
+## Overview
+
+Connect Okta from the Asymptote dashboard to automatically populate the users, groups, and devices tabs.
+
+## Connect Okta
+
+1. Log in to the Asymptote dashboard.
+2. Go to **Connectors**.
+3. Find the Okta integration.
+4. Click **Connect**.
+5. Enter your Okta org URL.
+6. Enter your Okta API token.
+
+After the connector is authorized, Asymptote automatically syncs Okta data into the users, groups, and devices tabs in the dashboard.
+
+## Generate an Okta API Token
+
+Create the Okta API token from the Okta Admin Console:
+
+1. Go to **Security**.
+2. Open **API**.
+3. Select **Tokens**.
+4. Click **Create token**.
+
+Copy the generated token and paste it into the Okta connector setup flow in Asymptote.
diff --git a/docs/manage/onboarding.mdx b/docs/manage/onboarding.mdx
index a352d8b7..faa491ea 100644
--- a/docs/manage/onboarding.mdx
+++ b/docs/manage/onboarding.mdx
@@ -1,131 +1,5 @@
---
title: "Onboarding"
-description: "Configure read-only S3 access for Asymptote ingestion."
+description: "Onboarding guides for Asymptote managed connectors."
tag: "Enterprise"
---
-
-## Overview
-
-Asymptote can ingest customer-hosted event files from a private AWS S3 bucket or prefix. Grant Asymptote's ingestion worker read-only access to the bucket that contains the event files.
-
-Do not make the bucket public. Do not grant write or delete permissions.
-
-At the end of setup, send Asymptote the full IAM role ARN for the role you create.
-
-## Customer Steps
-
-1. Send Asymptote the S3 location details.
-
- Include:
-
- - AWS account ID
- - S3 bucket name
- - AWS region
- - Prefix/path for the event files, such as `s3://your-bucket/asymptote/events/`
- - File format, ideally JSONL or JSONEachRow
- - Delivery cadence and approximate event volume
- - Encryption type, either SSE-S3 or SSE-KMS
- - KMS key ARN, only if SSE-KMS is enabled
-
-2. Create a dedicated IAM role in AWS.
-
- Sign in to the AWS account that owns the S3 bucket with an IAM user that can create and manage IAM roles. Open the IAM service console, then create a new role named something like `asymptote-s3-read`.
-
-3. Configure the role trust policy.
-
- Use the IAM ARN Asymptote gives you as the trusted principal. Replace `ASYMPTOTE_IAM_ARN` with that ARN.
-
- ```json title="IAM role trust policy"
- {
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Principal": {
- "AWS": "ASYMPTOTE_IAM_ARN"
- },
- "Action": "sts:AssumeRole"
- }
- ]
- }
- ```
-
-4. Attach a read-only S3 policy.
-
- ```json title="Read-only S3 policy"
- {
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": [
- "s3:GetBucketLocation",
- "s3:ListBucket"
- ],
- "Resource": [
- "arn:aws:s3:::YOUR_BUCKET_NAME"
- ]
- },
- {
- "Effect": "Allow",
- "Action": [
- "s3:Get*",
- "s3:List*"
- ],
- "Resource": [
- "arn:aws:s3:::YOUR_BUCKET_NAME/*"
- ]
- }
- ]
- }
- ```
-
- Replace `YOUR_BUCKET_NAME` with the name of the S3 bucket that contains the event files.
-
-5. Add KMS decrypt permission if needed.
-
- If the bucket uses SSE-KMS, add this statement to the role policy:
-
- ```json title="SSE-KMS decrypt statement"
- {
- "Sid": "DecryptEventObjects",
- "Effect": "Allow",
- "Action": "kms:Decrypt",
- "Resource": "YOUR_KMS_KEY_ARN"
- }
- ```
-
- The KMS key policy must also allow this IAM role to use `kms:Decrypt`.
-
-6. Send Asymptote the final onboarding details.
-
- Send:
-
- - IAM role ARN for the role you created
- - S3 URL/prefix
- - AWS region
- - KMS key ARN, if applicable
- - A small sample event file or example JSONL row
-
-## Event File Requirements
-
-Use newline-delimited JSON, with one complete JSON object per line. Each event should include a UTC-compatible timestamp and stable fields for user, host, repository, branch, agent runtime, event action, and event category when available.
-
-Share a representative sample file before production ingestion. The sample should show realistic field names and value shapes, but should not include secrets.
-
-## Related
-
-<Columns cols={2}>
- <Card title="Asymptote Managed" icon="cloud" href="/deployment/managed">
- Review managed visibility, governance, and investigation workflows.
- </Card>
- <Card title="Endpoint Event Schema" icon="code" href="/telemetry-schema/event-schema">
- Review normalized event fields and example payloads.
- </Card>
- <Card title="AWS S3 Forwarding" icon="bucket" href="/log-forwarding/s3">
- Configure customer-managed Beacon event forwarding into S3.
- </Card>
- <Card title="Data Inventory" icon="table-list" href="/security/data-inventory">
- Review the endpoint event fields Beacon can write.
- </Card>
-</Columns>
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 6b365d2d..b05fdb78 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -54,6 +54,17 @@ Application certificate, set `PKG_SIGN_IDENTITY` to sign the package with a
Developer ID Installer certificate, and set `NOTARYTOOL_PROFILE` to submit and
staple the package with Apple's notary service.
+For release artifacts, use the signing wrapper so required identities are checked
+up front and the final package signature, stapled ticket, Gatekeeper assessment,
+and checksum are verified:
+
+```bash
+BEACON_APP_SIGN_IDENTITY="Developer ID Application: Example Corp (TEAMID)" \
+PKG_SIGN_IDENTITY="Developer ID Installer: Example Corp (TEAMID)" \
+NOTARYTOOL_PROFILE="beacon-notary-profile" \
+ sh packaging/macos/build-signed-notarized-pkg.sh
+```
+
## Manual Install
```bash
diff --git a/packaging/macos/build-signed-notarized-pkg.sh b/packaging/macos/build-signed-notarized-pkg.sh
new file mode 100755
index 00000000..3621d2fb
--- /dev/null
+++ b/packaging/macos/build-signed-notarized-pkg.sh
@@ -0,0 +1,123 @@
+#!/bin/sh
+set -eu
+export COPYFILE_DISABLE=1
+
+ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+PKG_BUILD_SCRIPT="$ROOT_DIR/packaging/macos/build-pkg.sh"
+OUT_DIR="${OUT_DIR:-}"
+SKIP_VERIFY=0
+BUILD_LOG="$(mktemp)"
+trap 'rm -f "$BUILD_LOG"' EXIT INT TERM
+
+usage() {
+ cat <<'USAGE'
+Usage:
+ BEACON_APP_SIGN_IDENTITY="Developer ID Application: Example Corp (TEAMID)" \
+ PKG_SIGN_IDENTITY="Developer ID Installer: Example Corp (TEAMID)" \
+ NOTARYTOOL_PROFILE="beacon-notary-profile" \
+ sh packaging/macos/build-signed-notarized-pkg.sh [options]
+
+Options:
+ --out-dir DIR Write the package to DIR instead of dist/macos.
+ --version VERSION Override the package version.
+ --skip-verify Skip pkgutil, stapler, and spctl verification.
+ -h, --help Show this help.
+
+The script builds a fresh package so payload binaries can be signed before they
+are sealed into the installer. Configure notarytool once with:
+
+ xcrun notarytool store-credentials beacon-notary-profile \
+ --apple-id [email protected] --team-id TEAMID --password "$APP_SPECIFIC_PASSWORD"
+USAGE
+}
+
+die() {
+ echo "error: $*" >&2
+ exit 1
+}
+
+require_env() {
+ name="$1"
+ eval "value=\${$name:-}"
+ if [ -z "$value" ]; then
+ die "$name is required"
+ fi
+}
+
+require_command() {
+ command -v "$1" >/dev/null 2>&1 || die "$1 is required"
+}
+
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --out-dir)
+ [ "$#" -ge 2 ] || die "--out-dir requires a value"
+ OUT_DIR="$2"
+ shift 2
+ ;;
+ --version)
+ [ "$#" -ge 2 ] || die "--version requires a value"
+ BEACON_VERSION="$2"
+ export BEACON_VERSION
+ shift 2
+ ;;
+ --skip-verify)
+ SKIP_VERIFY=1
+ shift
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ die "unknown argument: $1"
+ ;;
+ esac
+done
+
+if [ "$(uname -s)" != "Darwin" ]; then
+ die "Apple signing and notarization must run on macOS"
+fi
+
+require_env BEACON_APP_SIGN_IDENTITY
+require_env PKG_SIGN_IDENTITY
+require_env NOTARYTOOL_PROFILE
+
+require_command codesign
+require_command pkgbuild
+require_command pkgutil
+require_command shasum
+require_command spctl
+require_command xcrun
+xcrun --find notarytool >/dev/null 2>&1 || die "xcrun notarytool is required"
+xcrun --find stapler >/dev/null 2>&1 || die "xcrun stapler is required"
+
+echo "building, signing, notarizing, and stapling macOS package..."
+if [ -n "$OUT_DIR" ]; then
+ export OUT_DIR
+fi
+
+if ! sh "$PKG_BUILD_SCRIPT" >"$BUILD_LOG" 2>&1; then
+ sed -n '1,$p' "$BUILD_LOG" >&2
+ die "package build failed"
+fi
+PKG_OUTPUT="$(sed -n '1,$p' "$BUILD_LOG")"
+printf '%s\n' "$PKG_OUTPUT"
+PKG_PATH="$(printf '%s\n' "$PKG_OUTPUT" | sed -n '$p')"
+[ -n "$PKG_PATH" ] || die "package build did not report an output path"
+[ -f "$PKG_PATH" ] || die "package not found: $PKG_PATH"
+
+if [ "$SKIP_VERIFY" -eq 0 ]; then
+ echo "verifying package signature..."
+ pkgutil --check-signature "$PKG_PATH"
+
+ echo "validating stapled notarization ticket..."
+ xcrun stapler validate "$PKG_PATH"
+
+ echo "checking Gatekeeper install assessment..."
+ spctl -a -vv -t install "$PKG_PATH"
+fi
+
+shasum -a 256 "$PKG_PATH" > "$PKG_PATH.sha256"
+echo "signed and notarized package: $PKG_PATH"
+echo "checksum: $PKG_PATH.sha256"
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index c8e87528..f0e7a512 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -70,9 +70,14 @@ Create, submit, and staple a signed/notarized package:
BEACON_APP_SIGN_IDENTITY="Developer ID Application: Example Corp (TEAMID)" \
PKG_SIGN_IDENTITY="Developer ID Installer: Example Corp (TEAMID)" \
NOTARYTOOL_PROFILE="beacon-notary-profile" \
- sh packaging/macos/build-pkg.sh
+ sh packaging/macos/build-signed-notarized-pkg.sh
```
+The wrapper delegates package assembly to `build-pkg.sh`, so payload binaries
+are signed before they are sealed into the installer. It then verifies the
+package signature with `pkgutil`, validates the stapled notarization ticket,
+runs Gatekeeper's install assessment, and rewrites the SHA-256 checksum.
+
The package installs files under `/opt/beacon` and runs
`/opt/beacon/scripts/install-endpoint.sh` in `postinstall` with explicit
collector settings, matching the shared MDM install wrapper.
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index d51b22c6..34f936be 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -5,6 +5,7 @@ ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
INSTALL_SCRIPT="$ROOT_DIR/packaging/macos/install-endpoint.sh"
UNINSTALL_SCRIPT="$ROOT_DIR/packaging/macos/uninstall-endpoint.sh"
PKG_BUILD_SCRIPT="$ROOT_DIR/packaging/macos/build-pkg.sh"
+PKG_SIGN_NOTARIZE_SCRIPT="$ROOT_DIR/packaging/macos/build-signed-notarized-pkg.sh"
REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/jamf/scripts/repair.sh"
FLEET_REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/fleet/scripts/repair.sh"
TMP_DIR="$(mktemp -d)"
@@ -13,6 +14,7 @@ trap 'rm -rf "$TMP_DIR"' EXIT INT TERM
sh -n "$INSTALL_SCRIPT"
sh -n "$UNINSTALL_SCRIPT"
sh -n "$PKG_BUILD_SCRIPT"
+sh -n "$PKG_SIGN_NOTARIZE_SCRIPT"
for script in "$ROOT_DIR"/packaging/macos/scripts/* "$ROOT_DIR"/packaging/macos/jamf/scripts/*.sh "$ROOT_DIR"/packaging/macos/jamf/claude/*/*.sh "$ROOT_DIR"/packaging/macos/jamf/extension-attributes/*.sh "$ROOT_DIR"/packaging/macos/fleet/scripts/*.sh; do
case "$script" in
*/repair-hooks.sh)