feat: add ISE agent quick-start guide

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Generate release checksums
-        run: sha256sum install.sh start.sh agentctl docker-compose.yml > SHA256SUMS
+        run: sha256sum install.sh QUICKSTART.md start.sh agentctl docker-compose.yml > SHA256SUMS
 
       - name: Publish release assets
         env:
@@ -41,6 +41,7 @@ jobs:
           tag="release-${GITHUB_SHA::12}"
           gh release create "${tag}" \
             install.sh \
+            QUICKSTART.md \
             start.sh \
             agentctl \
             docker-compose.yml \

AGENTS.md

@@ -9,6 +9,11 @@ owns the application and collection behavior inside the image.
 
 - Keep the host layer thin. It may adapt the host environment to the container
   runtime, but it should not duplicate application logic from the image.
+- For onboarding, documentation, and setup-only improvements, target new
+  installations by default. Do not make existing customers perform a manual
+  host-tool or agent update unless the user explicitly requests it or the
+  update is strictly necessary for correctness or security. If a manual update
+  is unavoidable, explain the necessity before implementing it.
 - Put parsing, business rules, collection behavior, artifact construction, and
   other application-specific work in the image behind a stable public
   interface.

QUICKSTART.md

@@ -0,0 +1,107 @@
+# Cisco Identity Intelligence ISE Agent Quick Start
+
+Use this guide to prepare Cisco ISE, install the on-premises agent, and verify
+the first connection. For complete setup and troubleshooting guidance, see the
+[Cisco ISE integration documentation](https://docs.oort.io/integrations/cisco-identity-services-engine-ise).
+
+## Before you start
+
+- Use Cisco ISE 3.3 or later with ERS, the required endpoint APIs, and pxGrid
+  enabled.
+- Prepare a dedicated, access-controlled host directory. The host needs Docker
+  with Compose, or Podman with a Compose provider.
+- Create a dedicated internal ISE administrator account for the agent. Assign
+  **ERS Operator** and **MnT Admin**. Use **ERS Admin** instead of ERS Operator
+  only if the integration needs to perform write actions.
+- Allow the agent host to reach the configured ISE API port (TCP 443 by
+  default) and the applicable ISE pxGrid nodes on TCP 8910.
+- Allow outbound TCP 443 to the `IOT_ENDPOINT` included in `.env`, GitHub
+  release and GHCR endpoints, and hosts used by signed S3 upload URLs. If a
+  proxy is required, it must allow HTTP CONNECT on port 443; enter it as an
+  `http://` URL during credential setup.
+- In ISE, go to **Administration > pxGrid Services > Settings**, enable
+  **Allow password based account creation**, and select **Save**. This setting
+  is disabled by default and is separate from enabling pxGrid on a deployment
+  node.
+- Arrange for an ISE administrator to approve the agent's pxGrid client if you
+  will create a new one.
+
+## Protect the deployment material
+
+The downloaded package and copied install command contain a sensitive,
+one-time bootstrap token. Complete setup within 24 hours of generating them,
+transfer them only to the intended agent host, and do not paste them into chat
+or support tickets. If the token expires, reset the agent credentials in the
+ISE integration and use the newly generated package or command.
+
+Do not edit the tenant ID, agent ID, IoT endpoint, topic prefix, certificate,
+or private key included with the deployment.
+
+## Install the agent
+
+Use a dedicated directory that does not contain unrelated environment,
+certificate, Compose, or launcher files.
+
+### Copied install command
+
+```sh
+mkdir -p ~/ise-agent
+cd ~/ise-agent
+# Paste the complete command copied from Cisco Identity Intelligence.
+```
+
+The installer creates the deployment files and starts first-run credential and
+pxGrid setup.
+
+### Downloaded ZIP
+
+Transfer the ZIP using your organization's approved secure method, extract the
+complete package into a dedicated directory, and run:
+
+```sh
+cd ~/ise-agent
+chmod +x ./start.sh
+./start.sh
+```
+
+## Complete first-run setup
+
+1. Enter the ISE hostname, username, password, and API port. The password is
+   saved in the agent's encrypted credential store, not in `.env`.
+2. Enter an outbound HTTPS proxy only if required. Use an `http://host:port`
+   URL; the proxy must support HTTP CONNECT to port 443.
+3. Choose how to configure pxGrid:
+   - **Create a new pxGrid client:** accept `cii-agent` or enter a
+     deployment-specific node name. After the agent starts, approve that client
+     under **Administration > pxGrid Services > Client Management > Clients**.
+   - **Use an existing client:** enter the name and password of a pxGrid client
+     that is already registered and approved.
+
+pxGrid is required for real-time session events and complete session data.
+
+## Verify the connection
+
+1. Confirm the agent container is running.
+2. Follow its logs and confirm that it connects to IoT Core, pxGrid activates,
+   the WebSocket connects, and collection starts.
+3. Return to **Integrations** in Cisco Identity Intelligence, open the existing
+   ISE integration, and select **Agent is running** after the first heartbeat
+   appears.
+
+To find the generated container name and inspect recent logs:
+
+```sh
+grep 'container_name:' docker-compose.yml
+
+# Docker
+docker compose ps
+docker logs --tail 200 -f <container_name>
+
+# Podman
+podman ps
+podman logs --tail 200 -f <container_name>
+```
+
+If pxGrid reports that it is waiting for approval, approve the displayed client
+in ISE. For connection timeouts, verify DNS, routing, the configured ISE API
+port, and TCP 8910 access to the applicable pxGrid nodes.

README.md

@@ -18,7 +18,7 @@ curl -fsSL "https://github.com/duosecurity/ise-agent/releases/latest/download/in
 This will:
 1. Decode your IoT credentials from the bundle
 2. Write `.env` and `certs/` to `~/ise-agent/`
-3. Download the stable `start.sh` bootstrap, versioned `agentctl`, and `docker-compose.yml`
+3. Download the customer quick-start guide, stable `start.sh` bootstrap, versioned `agentctl`, and `docker-compose.yml`
 4. Start the agent
 
 The generated `.env` only includes connection settings. The agent image applies
@@ -30,7 +30,8 @@ Alternatively, download the agent package ZIP from the UI and run `./start.sh` m
 ## Releasing
 
 Every merge to `main` publishes a GitHub Release containing `install.sh`, the
-stable `start.sh` bootstrap, versioned `agentctl`, `docker-compose.yml`, and
+customer `QUICKSTART.md`, stable `start.sh` bootstrap, versioned `agentctl`,
+`docker-compose.yml`, and
 SHA-256 checksums. The workflow creates a commit-specific
 `release-<commit>` tag automatically, so no manual tag is required.
 
@@ -105,6 +106,7 @@ settings in ISE:
 | File | Description |
 |------|-------------|
 | `install.sh` | Bootstrap script for one-line installation |
+| `QUICKSTART.md` | Customer setup guide installed as `README.md` by curl and ZIP installations |
 | `start.sh` | Stable bootstrap for the cached host controller |
 | `agentctl` | Versioned Docker/Podman and Compose lifecycle controller |
 | `docker-compose.yml` | Generated container definition (populated by install or update) |

install.sh

@@ -66,6 +66,7 @@ trap cleanup EXIT
 
 for target in \
   "${INSTALL_DIR}/.env" \
+  "${INSTALL_DIR}/README.md" \
   "${INSTALL_DIR}/docker-compose.yml" \
   "${INSTALL_DIR}/start.sh" \
   "${INSTALL_DIR}/.launcher/agentctl" \
@@ -79,6 +80,7 @@ done
 
 echo "Downloading the current ISE agent launcher..."
 curl -fsSL "${RELEASE_ASSET_BASE}/SHA256SUMS" -o "${TEMP_DIR}/SHA256SUMS"
+curl -fsSL "${RELEASE_ASSET_BASE}/QUICKSTART.md" -o "${TEMP_DIR}/QUICKSTART.md"
 curl -fsSL "${RELEASE_ASSET_BASE}/docker-compose.yml" -o "${TEMP_DIR}/docker-compose.yml.template"
 curl -fsSL "${RELEASE_ASSET_BASE}/start.sh" -o "${TEMP_DIR}/start.sh"
 curl -fsSL "${RELEASE_ASSET_BASE}/agentctl" -o "${TEMP_DIR}/agentctl"
@@ -102,6 +104,7 @@ verify_asset() {
   fi
 }
 
+verify_asset QUICKSTART.md "${TEMP_DIR}/QUICKSTART.md"
 verify_asset start.sh "${TEMP_DIR}/start.sh"
 verify_asset agentctl "${TEMP_DIR}/agentctl"
 verify_asset docker-compose.yml "${TEMP_DIR}/docker-compose.yml.template"
@@ -141,6 +144,7 @@ CONTAINER_NAME="ise-agent-${AGENT_SUFFIX}"
 sed "s|__CONTAINER_NAME__|${CONTAINER_NAME}|g; s|__AGENT_SUFFIX__|${AGENT_SUFFIX}|g" \
   "${TEMP_DIR}/docker-compose.yml.template" > "${TEMP_DIR}/docker-compose.yml"
 mkdir -p "${INSTALL_DIR}/.launcher"
+mv "${TEMP_DIR}/QUICKSTART.md" "${INSTALL_DIR}/README.md"
 mv "${TEMP_DIR}/docker-compose.yml" "${INSTALL_DIR}/docker-compose.yml"
 mv "${TEMP_DIR}/start.sh" "${INSTALL_DIR}/start.sh"
 mv "${TEMP_DIR}/agentctl" "${INSTALL_DIR}/.launcher/agentctl"

tests/test-host-tools.sh

@@ -39,12 +39,13 @@ mkdir -p \
 cp "${REPOSITORY_ROOT}/start.sh" "${RELEASE_DIR}/start.sh"
 cp "${REPOSITORY_ROOT}/agentctl" "${RELEASE_DIR}/agentctl"
 cp "${REPOSITORY_ROOT}/docker-compose.yml" "${RELEASE_DIR}/docker-compose.yml"
+cp "${REPOSITORY_ROOT}/QUICKSTART.md" "${RELEASE_DIR}/QUICKSTART.md"
 (
   cd "${RELEASE_DIR}"
   if command -v sha256sum &>/dev/null; then
-    sha256sum start.sh agentctl docker-compose.yml > SHA256SUMS
+    sha256sum QUICKSTART.md start.sh agentctl docker-compose.yml > SHA256SUMS
   else
-    shasum -a 256 start.sh agentctl docker-compose.yml > SHA256SUMS
+    shasum -a 256 QUICKSTART.md start.sh agentctl docker-compose.yml > SHA256SUMS
   fi
 )