The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
update docs, add script to notarize
Justin D'Souzafa42de613bbc
diff --git a/docs/docs.json b/docs/docs.jsonindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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.mdindex 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 aDeveloper ID Installer certificate, and set `NOTARYTOOL_PROFILE` to submit andstaple 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```bashdiff --git a/packaging/macos/build-signed-notarized-pkg.sh b/packaging/macos/build-signed-notarized-pkg.shnew file mode 100755index 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.mdindex 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 explicitcollector settings, matching the shared MDM install wrapper.diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.shindex 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 TERMsh -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; docase "$script" in*/repair-hooks.sh)