diff --git a/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/operational.md b/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/operational.md index d0eccd89e2..51dd999e96 100644 --- a/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/operational.md +++ b/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/operational.md @@ -10,8 +10,7 @@ Operational Maintenance # Operational Maintenance -Once Privilege Secure is rolled out there are various maintenance and operational items that should -be done at regular intervals: +Once Privilege Secure is deployed, perform the following maintenance and operational tasks at regular intervals: ## Privilege Secure Processes (suggested daily) @@ -22,17 +21,15 @@ be done at regular intervals: ![image.webp](/images/privilegesecure/4.2/discovery/admin/maintenance/360053539334_image.webp) -- The manager status should be listed as "Leader" for a single node or "Leader" and "Reachable" as - above. The Leader is the primary manager node and the Reachable nodes are managers. In the event +- The manager status shows "Leader" for a single node or "Leader" and "Reachable" for a cluster. The Leader is the primary manager node and the Reachable nodes are managers. In the event of a failure of a node an election to determine a new primary manager takes place. A single node can fail without any indication to users. ## Disk Maintenance (suggested weekly) -- Disk space should be checked on a periodic basis. The command to check this is: df -h -- This command is disk free with the switch h for human readable. Disk usage over 80% should be - checked to see if there are any specific reasons for excessive disk usage. If this the space can - not be reduced successfully, additional disc space should be added. The Customer Success team can +- Check disk space periodically. The command is: df -h +- This command is disk free with the switch h for human readable. Investigate disk usage over 80% for specific causes of excessive usage. If the space can't be + reduced successfully, add additional disk space. The Customer Success team can assist with the review and reduction of used disc space and also increase of disk space (physical or virtual, dependent on environment). @@ -40,9 +37,9 @@ be done at regular intervals: Review (suggested weekly) -- Check that backups are being executed on the production node and successfully copied to DR. -- Confirm that backups with appropriate recent date exist on DR server. Backups are usually executed - from a cron run script daily. +- Check that backups are running on the production node and copying successfully to DR. +- Confirm that backups with appropriate recent date exist on DR server. A cron script typically runs + backups daily. - If the backup is set to restore the database backup daily, check the logs for any errors. - Production Primary Node: - ls -lath /secureone/data/db/backups @@ -51,39 +48,36 @@ Review (suggested weekly) Test (suggested minimum yearly) -- It is recommended to test DR at least yearly. This can be part of a wider DR test or specific to +- Test DR at least yearly. This can be part of a wider DR test or specific to Privilege Secure. -- A test window should be created for this as changes to Privilege Secure DR would not be propagated - back to the main production instance. +- Create a test window, since changes to Privilege Secure DR don't propagate back to the main production instance. - After a test ensure that services are down on the DR node. This will avoid the DR environment - overriding changes from Production. The command below can be utilized for this: + overriding changes from Production. Use the following command: - `s1 stop expire worker scanner` ## Run Quickstart to Review Protect Mode and Persistence (suggested weekly) -- Quickstart should be run frequently to ensure that all machines remain in protect mode. The output - from Quickstart can be filtered for any machines that do not show in protect mode. This - ensures that the build process and addition or protect mode is being executed as expected. +- Run Quickstart frequently to ensure that all machines remain in protect mode. Filter the Quickstart + output for any machines that don't show in protect mode. This ensures that the build process and + addition of protect mode runs as expected. - Quickstart can also be used for a review of persistent access. This should be minimized to service - accounts. A review to look for user accounts set to persistent should be carried out. If these are + accounts. A review to look for user accounts set to persistent should be performed. If these are truly required to be persistent, then they should be switched to a service account. ## Privilege Secure Log Review - SIEM (suggested weekly) -- Typically a SIEM solution is best placed to report any issues that can be captured in Privilege - Secure logs. -- An example set of queries for Splunk is included here: - [Splunk and SIEM Queries](../../integrations/siem/splunkqueries.md) -- The "change system policy" output should be reviewed for any removal of protect mode. -- The "slow JITA access" and "time it takes for JITA access" can give an indication if users are - being slowed down in their ability to elevate privilege when utilizing Privilege Secure. +- Typically, a SIEM solution best reports issues that Privilege Secure logs capture. +- For Splunk query examples, see [Splunk and SIEM Queries](../../integrations/siem/splunkqueries.md). +- Review the "change system policy" output for any removal of protect mode. +- The "slow JITA access" and "time it takes for JITA access" indicate whether users experience slow + privilege elevation when using Privilege Secure. ## Mongo Health (suggested weekly) Time Sync -- Run the following command to check that the servers are remaining in sync with time: +- Run the following command to check that servers remain in sync: - sudo docker exec -it $(sudo docker ps | grep mongo | cut -d' ' -f1) mongo SecureONE --eval 'rs.printSlaveReplicationInfo()' - The result should show that there is little or no difference in time: @@ -99,7 +93,7 @@ Time Sync source: mongo3:27017 syncedTo: Tue Sep 22 2020 16:03:34 GMT+0000 (UTC) 0 secs (0 hrs) behind the primary -- In the event of a variation in time, contact the Remediant Customer Success team. +- If there is a variation in time, contact the Remediant Customer Success team. Mongo status @@ -131,7 +125,10 @@ sudo docker exec -it $(sudo docker ps | grep mongo | cut -d' ' -f1) mongo Secure ## Version and OS updates (suggested quarterly minimum) - Ensure quarterly meeting to review updates to Privilege Secure version and OS patches/updates. -- Patches can be applied monthly. The Customer Success team can be contacted prior to updates to +- Patches can be applied monthly. The Customer Success team can be contacted before updates to ensure no known issues. +**See also:** [Docker Credentials Helper](../../installation/dockercredentials.md) — secure +credential storage for pulling private registry images during NPSD deployment and upgrades. + diff --git a/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/updateosonappliances.md b/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/updateosonappliances.md index 77478cfe6b..4d2c14a119 100644 --- a/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/updateosonappliances.md +++ b/docs/privilegesecurediscovery/2.22/administration/onpremmaintenance/updateosonappliances.md @@ -16,8 +16,8 @@ update require a reboot of the server or Docker service. There are different options to fit your environment or downtime tolerance. -- Cluster:  No downtime -- Single-Node:  Downtime during reboot +- Cluster: No downtime +- Single-Node: Downtime during reboot This is a guide to updating the OS on Privilege Secure node with that best practice in mind. Privilege Secure will be offline for 30-60 minutes. @@ -29,7 +29,7 @@ Privilege Secure will be offline for 30-60 minutes. ## Use Case: Cluster In-Place (1 node at a Time, No Downtime) -Check DB replication status, “stateStr” should be “PRIMARY” or "SECONDARY"; and replication time +Check DB replication status, "stateStr" should be "PRIMARY" or "SECONDARY"; and replication time difference, a few seconds is acceptable: ``` @@ -39,7 +39,7 @@ mEvl ``` -**NOTE:** If the database replication is not in healthy state, resolve that before continuing. +**NOTE:** If the database replication isn't in healthy state, resolve that before continuing. Primary node only: Check Privilege Secure services and nodes status: @@ -53,12 +53,12 @@ Check for the swarm leader: s1 nodes | grep Leader ``` -Only if the node being updated has a MANAGER STATUS of leader, run the below command on a different -node to change the swarm Leader.  Replace `` with the hostname of the node being upgraded -and run the command below. +Only if the node being updated has a MANAGER STATUS of leader, run the following command on a +different node to change the swarm Leader, replacing `` with the hostname of the node +being upgraded: ``` -HNupg=`` ;  sudo docker node demote $HNupg; sleep 10; sudo docker node promote $HNupg +HNupg=`` ; sudo docker node demote $HNupg; sleep 10; sudo docker node promote $HNupg ``` Verify swarm leader is no longer the node being updated: @@ -78,7 +78,7 @@ Drain node to be updated: - sudo docker node update --availability drain `` -Verify “Availability” is set to “Drain” with: +Verify "Availability" is set to "Drain" with: - s1 nodes @@ -98,8 +98,8 @@ existing configurations, setting, or file. **Step 3 –** Reboot if required. - sudo cat /var/run/reboot-required -- Result if reboot is required:  "\*\*\* System restart required \*\*\*" -- Result if reboot not required:  "cat: /var/run/reboot-required: No such file or directory" +- Result if reboot is required: "\*\*\* System restart required \*\*\*" +- Result if reboot not required: "cat: /var/run/reboot-required: No such file or directory" - If required, reboot node: - sudo reboot @@ -114,10 +114,10 @@ existing configurations, setting, or file. - watch s1 nodes - - Verify “Availability” is set to “Active” on updated node. + - Verify "Availability" is set to "Active" on updated node. -- Once the updated node is reachable, Ctrl+C to get out of the watch command -- Check DB replication status, “stateStr” should be “PRIMARY” or "SECONDARY"; and replication time +- After the updated node is reachable, press Ctrl+C to stop the watch command +- Check DB replication status, "stateStr" should be "PRIMARY" or "SECONDARY"; and replication time difference, a few seconds is acceptable: - ``` mEvl="sudo docker exec -it $(sudo docker ps | grep mongo | cut -d' ' -f1) mongo SecureONE --quiet --eval"; $mEvl 'rs.status()' | grep "name\|stateStr\|lastHeartbeatRecv\|lastHeartbeatMessage" | column -t; echo; $mEvl 'rs.printSlaveReplicationInfo()'; unset mEvl @@ -154,8 +154,8 @@ existing configurations, setting, or file. - sudo cat /var/run/reboot-required - - Result if reboot is required:  "\*\*\* System restart required \*\*\*" - - Result if reboot not required:  "cat: /var/run/reboot-required: No such file or directory" + - Result if reboot is required: "\*\*\* System restart required \*\*\*" + - Result if reboot not required: "cat: /var/run/reboot-required: No such file or directory" - If required, reboot node: - sudo reboot @@ -164,4 +164,6 @@ existing configurations, setting, or file. - s1 status; s1 nodes +**See also:** [Docker Credentials Helper](../../installation/dockercredentials.md) — secure +credential storage required when pulling private registry images during NPSD upgrades. diff --git a/docs/privilegesecurediscovery/2.22/installation/dockercredentials.md b/docs/privilegesecurediscovery/2.22/installation/dockercredentials.md new file mode 100644 index 0000000000..8b11269d74 --- /dev/null +++ b/docs/privilegesecurediscovery/2.22/installation/dockercredentials.md @@ -0,0 +1,708 @@ +--- +title: "Docker Credentials Helper" +description: "Docker Credentials Helper" +sidebar_position: 50 +--- + +# Docker Credentials Helper + +## What This Guide Installs + +This guide sets up the official `docker-credential-pass` helper from +[docker/docker-credential-helpers](https://github.com/docker/docker-credential-helpers) with +`gopass` as the encrypted backend store. Instead of Docker writing base64-encoded credentials into +`~/.docker/config.json`, credentials are encrypted with GPG and stored through `gopass`. + +The main operational use case is deploying or upgrading NPS-D on a customer machine that needs to +pull private images from a protected registry. The standard deployment model is local only: one +encrypted `gopass` store per engineer or per machine, with no Git remote required. + +## How It Works + +Docker calls the `docker-credential-pass` binary for credential storage and retrieval. That binary +expects to talk to the `pass` CLI and read from `~/.password-store/`. Since `gopass` is +CLI-compatible with `pass` and uses the same GPG-encrypted file format, two symlinks bridge the +gap: + +1. **`gopass` symlinked as `pass`** — so `docker-credential-pass` can find the binary it expects +2. **gopass store symlinked to `~/.password-store/`** — so filesystem reads land in the right place + +``` +Docker CLI --docker login--> docker-credential-pass (official binary) + | + v + pass (symlink -> gopass) + | + v + GPG-encrypted store + (~/.password-store -> gopass store) +``` + +Repo assets: + +- Ubuntu/WSL installer: `scripts/docker-credential-gopass/install-ubuntu.sh` +- Ubuntu validator: `scripts/docker-credential-gopass/validate-ubuntu-login.sh` +- macOS validator: `scripts/docker-credential-gopass/validate-macos-login.sh` +- macOS passphrase validator: `scripts/docker-credential-gopass/validate-macos-passphrase-login.sh` +- Shared store sync validator: `scripts/docker-credential-gopass/validate-shared-store-sync.sh` + +## Prerequisites + +### NPS-D platform requirements + +- NPS-D 2.22.13, 26.03.01, or later + +### Runtime prerequisites (all platforms) + +- Docker CLI +- Access to a running Docker-compatible daemon or engine +- GnuPG / `gpg` +- Git +- `gopass` + +:::note +A Git remote isn't required for the standard NPS-D customer-machine deployment flow. `git` is still +installed in the validated path because `gopass` defaults to a local Git-backed store, even when no +remote is configured. +::: + +### Production prerequisite + +If your GPG key is passphrase-protected, you need a working `pinentry` program and `gpg-agent` +configuration so `gopass` can decrypt during `docker login`. + +### Validation prerequisites + +- Ability to pull and run `registry:2` and `docker:dind` +- Permission to run a privileged container for the Ubuntu DinD validator +- Free local ports `23750`, `5002`, and `5004` if you run the validated login flows on the same + machine + +## Supported Platforms + +- Linux amd64 +- Linux arm64 +- macOS (Apple Silicon and Intel) + +:::note +Windows isn't supported by the official `docker-credential-pass` helper. For Windows environments, +use WSL Ubuntu with the Linux binary. +::: + +## Common Docker Configuration + +On every platform, configure Docker to use the helper by adding the following to the Docker config +file: + +```json +{ + "credsStore": "pass" +} +``` + +Docker will then execute `docker-credential-pass` when storing or retrieving credentials. + +This configuration is client-side. It doesn't depend on Docker Desktop and it still applies when +the Docker client talks to a remote engine. + +If the Docker config file already exists, replace only the `credsStore` key and keep the +other keys that the machine already uses. Don't leave registry credentials behind under `auths`. + +## Credential Store Context + +:::warning +This installer sets up GPG keys and the `gopass` credential store in the `HOME` directory of the +user who runs the script. Docker's credential helper (`docker-credential-pass`) resolves credentials +from the `$HOME` of whatever user invokes `docker` at runtime. + +This script assumes you run Docker commands as root (for example, via `sudo docker`). Run the +installer accordingly: + +```bash +sudo -H bash install.sh # correct — $HOME resolves to /root +sudo bash install.sh # WRONG — $HOME stays as the calling user's home +``` + +If Docker runs as a non-root user (for example, via docker group membership or a dedicated service +account), run this installer as that user instead: + +```bash +sudo -u ci-runner -H bash install.sh +``` + +Mismatched contexts will cause silent credential lookup failures at `docker pull`. +::: + +## AWS Credentials Configuration + +Pulling NPS-D images requires authentication to the AWS ECR registry. Configure AWS credentials +before running `docker login`. + +:::note +The AWS Access Key ID and Secret Access Key for customer deployments are provided by the CS team. +This configuration is performed manually and is independent of the installer and validator scripts +in the repository — those scripts don't interact with AWS or ECR. +::: + +**Step 1 –** Install the AWS CLI if not already present: + +```bash +sudo apt-get install -y awscli # Ubuntu / WSL +brew install awscli # macOS +``` + +**Step 2 –** Configure AWS credentials for the operator account: + +```bash +sudo aws configure +``` + +Enter the values when prompted: + +``` +AWS Access Key ID: +AWS Secret Access Key: +Default region name: us-west-2 +Default output format: +``` + +**Step 3 –** Authenticate Docker to the registry: + +For NPS-D production deployments, set the registry variable and log in using the temporary ECR +token: + +```bash +export REGISTRY="176947481038.dkr.ecr.us-west-2.amazonaws.com" +export REGISTRY_USER="AWS" + +aws ecr get-login-password --region us-west-2 \ + | docker login --username "$REGISTRY_USER" --password-stdin "$REGISTRY" +``` + +Expected output: `Login Succeeded` + +This command uses your AWS credentials to get a temporary ECR token (valid 12 hours) and passes it +directly to `docker login`. `docker-credential-pass` then stores the encrypted token — +`~/.docker/config.json` receives no plain-text credentials. + +**Step 4 –** Verify the credential was stored correctly: + +```bash +grep -q '"auth"' "$HOME/.docker/config.json" && echo "unexpected inline auth found" +printf '%s' "$REGISTRY" | docker-credential-pass get +``` + +Expected result: + +- no `auth` entry written into Docker config +- helper output that includes `ServerURL`, `Username`, and `Secret`: + +```json +{ + "ServerURL": "176947481038.dkr.ecr.us-west-2.amazonaws.com", + "Username": "AWS", + "Secret": "" +} +``` + +--- + +## Recommended NPS-D Customer-Machine Workflow + +After the helper is installed and `gopass` is initialized for the operator account, the practical +deployment flow is the same on Ubuntu, WSL Ubuntu, and macOS. This workflow is intentionally local +only — it doesn't require a shared store or any Git remote. + +For Ubuntu and WSL Ubuntu, the recommended path is the installer script: + +```bash +./scripts/docker-credential-gopass/install-ubuntu.sh \ + --install-prereqs \ + --git-name "NPS-D Engineer" \ + --git-email engineer@example.com \ + --generate-gpg-key \ + --gpg-name "NPS-D Engineer" \ + --gpg-email engineer@example.com \ + --no-gpg-passphrase +``` + +`--install-prereqs` is optional. When present, the installer adds the Ubuntu packages and the +`gopass` apt repository before installing and configuring the helper. Without it, the installer +assumes the required packages are already present and only wires up the helper, the local `gopass` +store, and the Docker config. + +### Step 1: Confirm Docker is configured to use the helper + +The active Docker client config for the current user should contain: + +```json +{ + "credsStore": "pass" +} +``` + +Path on Linux, WSL, and macOS: `$HOME/.docker/config.json` + +### Step 2: Log in to the private registry used by the customer deployment + +Linux, WSL, or macOS: + +```bash +export REGISTRY="176947481038.dkr.ecr.us-west-2.amazonaws.com" +export REGISTRY_USER="AWS" + +aws ecr get-login-password --region us-west-2 \ + | docker login --username "$REGISTRY_USER" --password-stdin "$REGISTRY" +``` + +Expected output: `Login Succeeded` + +`docker-credential-pass` stores the encrypted temporary ECR token. `~/.docker/config.json` +receives no plain-text credentials. + +### Step 3: Verify the login result before deploying NPS-D + +```bash +grep -q '"auth"' "$HOME/.docker/config.json" && echo "unexpected inline auth found" +printf '%s' "$REGISTRY" | docker-credential-pass get +``` + +Expected result: + +- no `auth` entry written into Docker config +- helper output that includes `ServerURL`, `Username`, and `Secret` + +### Step 4: Run the NPS-D deployment or upgrade + +After the registry login is in place, use the existing NPS-D deployment mechanism for that customer +machine. + +Docker Compose: + +```bash +docker compose pull +docker compose up -d +``` + +Docker Swarm — keep `--with-registry-auth` on service creation or update commands: + +```bash +docker service create --with-registry-auth --name example "$REGISTRY/example/image:tag" +docker service update --with-registry-auth --image "$REGISTRY/example/image:tag" example +``` + +### Step 5: Log out when the deployment window is complete + +```bash +docker logout "$REGISTRY" +``` + +During logout, Docker asks the helper to delete the stored credential entry. + +## Operator Usage Notes + +- Docker uses the helper automatically after you configure `credsStore: pass`. Operators + don't need to invoke it directly during routine deployments. +- Credentials are scoped to the registry hostname. Log in separately for each registry the customer + environment needs. +- The standard deployment model is local only. One engineer account or one machine gets one local + encrypted store. You don't need a remote repository. +- `printf '%s' "$REGISTRY" | docker-credential-pass get` is a direct verification command when + operators need to confirm which credential is stored. +- `docker-credential-pass list` shows which registry entries exist. +- If a customer machine already uses another Docker credential store, switching `credsStore` to + `pass` changes the active credential backend for that Docker client. +- For customer-machine operators, prefer interactive `docker login` so you enter the token at + Docker's password prompt instead of placing it in shell history or environment variables. +- If unattended automation is required, only use `--password-stdin` from a secure secret source. + Don't hardcode the token into the command line or export it in the shell profile. + +--- + +## Ubuntu + +### Recommended installer path + +Run the installer from the repo root: + +```bash +./scripts/docker-credential-gopass/install-ubuntu.sh \ + --install-prereqs \ + --git-name "Your Name" \ + --git-email you@example.com \ + --generate-gpg-key \ + --gpg-name "Your Name" \ + --gpg-email you@example.com \ + --no-gpg-passphrase +``` + +Use `--gpg-key-id ` instead of `--generate-gpg-key ... --no-gpg-passphrase` if the operator +already has a suitable secret key. + +Use `--install-prereqs` when the machine still needs Ubuntu-side prerequisites installed. Omit it +when `gpg`, `git`, `gopass`, and Docker are already available. + +The installer performs these actions: + +- Optionally installs Ubuntu prerequisites and the `gopass` apt repository +- Downloads the official `docker-credential-pass` binary from GitHub releases +- Installs the binary as `docker-credential-pass` +- Creates a symlink from `gopass` to `pass` +- Configures global Git identity for the local `gopass` store +- Initializes a local `gopass` store +- Creates a symlink from the gopass store to `~/.password-store/` +- Configures Docker with `credsStore: pass` +- Removes any existing inline Docker `auths` entries unless `--keep-inline-auths` is specified + +### Manual step-by-step path + +**Step 1 –** Install prerequisites: + +```bash +sudo apt-get update +sudo apt-get install -y ca-certificates curl gnupg git docker.io python3 +``` + +**Step 2 –** Install `gopass`: + +```bash +curl -fsSL https://packages.gopass.pw/repos/gopass/gopass-archive-keyring.gpg \ + | sudo tee /usr/share/keyrings/gopass-archive-keyring.gpg >/dev/null +``` + +```bash +cat <<'EOF' | sudo tee /etc/apt/sources.list.d/gopass.sources >/dev/null +Types: deb +URIs: https://packages.gopass.pw/repos/gopass +Suites: stable +Architectures: all amd64 arm64 armhf +Components: main +Signed-By: /usr/share/keyrings/gopass-archive-keyring.gpg +EOF +``` + +```bash +sudo apt-get update +sudo apt-get install -y gopass gopass-archive-keyring +``` + +**Step 3 –** Download and install the official `docker-credential-pass`: + +```bash +ARCH="$(dpkg --print-architecture)" +VERSION="v0.9.5" +curl -fsSL "https://github.com/docker/docker-credential-helpers/releases/download/${VERSION}/docker-credential-pass-${VERSION}.linux-${ARCH}" \ + -o /tmp/docker-credential-pass +``` + +```bash +mkdir -p "$HOME/.local/bin" +install -m 0755 /tmp/docker-credential-pass "$HOME/.local/bin/docker-credential-pass" +``` + +If `$HOME/.local/bin` isn't already on `PATH`: + +```bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.profile" +export PATH="$HOME/.local/bin:$PATH" +``` + +**Step 4 –** Create the gopass symlinks: + +```bash +ln -sf "$(which gopass)" "$HOME/.local/bin/pass" +``` + +Create the store symlink after gopass initialization in step 8. + +**Step 5 –** Configure Git identity for the `gopass` store. This doesn't require any remote +repository: + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +**Step 6 –** Create a GPG key: + +```bash +cat > "$HOME/gpg-batch" <<'EOF' +Key-Type: RSA +Key-Length: 3072 +Subkey-Type: RSA +Subkey-Length: 3072 +Name-Real: Your Name +Name-Email: you@example.com +Expire-Date: 0 +%no-protection +%commit +EOF + +gpg --batch --generate-key "$HOME/gpg-batch" +``` + +:::note +To use a passphrase-protected key instead, remove `%no-protection` and ensure a working +`pinentry` program is configured before using `docker login`. +::: + +**Step 7 –** Get the key ID: + +```bash +KEYID="$(gpg --list-secret-keys --with-colons you@example.com | awk -F: '/^sec:/{print $5; exit}')" +echo "$KEYID" +``` + +**Step 8 –** Initialize `gopass` and create the store symlink: + +```bash +gopass --yes init "$KEYID" +``` + +```bash +ln -sfn "${XDG_DATA_HOME:-$HOME/.local/share}/gopass/stores/root" "$HOME/.password-store" +``` + +This creates the local encrypted store used by the helper and symlinks it to `~/.password-store/` +where `docker-credential-pass` expects to find it. For the standard NPS-D deployment flow, stop here +and don't add any remote. + +**Step 9 –** Configure Docker to use the helper: + +```bash +mkdir -p "$HOME/.docker" +cat > "$HOME/.docker/config.json" <<'EOF' +{ + "credsStore": "pass" +} +EOF +``` + +**Step 10 –** Log in to the NPS-D ECR registry: + +```bash +export REGISTRY="176947481038.dkr.ecr.us-west-2.amazonaws.com" +export REGISTRY_USER="AWS" + +aws ecr get-login-password --region us-west-2 \ + | docker login --username "$REGISTRY_USER" --password-stdin "$REGISTRY" +``` + +**Step 11 –** Verify that Docker didn't store inline credentials: + +```bash +grep -q '"auth"' "$HOME/.docker/config.json" && echo "unexpected inline auth found" +``` + +The expected result is no output. + +**Step 12 –** Verify helper retrieval: + +```bash +printf '%s' "$REGISTRY" | docker-credential-pass get +``` + +Expected output: + +```json +{"ServerURL":"176947481038.dkr.ecr.us-west-2.amazonaws.com","Username":"AWS","Secret":"..."} +``` + +**Step 13 –** Run the validated Ubuntu test harness from the repo root: + +```bash +bash ./scripts/docker-credential-gopass/validate-ubuntu-login.sh +``` + +This validator uses an Ubuntu 24.04 container plus a Docker-in-Docker sidecar and runs +`install-ubuntu.sh --install-prereqs` as part of the validation flow. + +--- + +## WSL Ubuntu + +Use the Ubuntu instructions above inside the WSL distro, with these differences: + +- Use the same installer script: + +```bash +./scripts/docker-credential-gopass/install-ubuntu.sh \ + --install-prereqs \ + --git-name "Your Name" \ + --git-email you@example.com \ + --gpg-key-id YOUR_KEY_ID +``` + +- The Docker CLI inside WSL must be able to reach a running daemon, but the helper, `gopass` store, + and GPG keys all stay inside the Linux distro. +- Write Docker config inside the distro at `$HOME/.docker/config.json`. +- Keep the `gopass` store and GPG key inside the distro filesystem. + +If you're using a Docker context or remote engine, `docker login` still uses the helper on the +client side inside WSL. + +--- + +## macOS + +Choose the correct target architecture: + +- Apple Silicon: `darwin-arm64` +- Intel: `darwin-amd64` + +**Step 1 –** Install prerequisites: + +```bash +brew install gnupg gopass git +``` + +If you plan to protect the GPG key with a passphrase, also install and configure a pinentry program: + +```bash +brew install pinentry-mac +mkdir -p "$HOME/.gnupg" +chmod 700 "$HOME/.gnupg" +PINENTRY="$(which pinentry-mac)" +echo "pinentry-program ${PINENTRY}" >> "$HOME/.gnupg/gpg-agent.conf" +gpgconf --kill gpg-agent +``` + +**Step 2 –** Download and install the official `docker-credential-pass`. + +Apple Silicon: + +```bash +curl -fsSL "https://github.com/docker/docker-credential-helpers/releases/download/v0.9.5/docker-credential-pass-v0.9.5.darwin-arm64" \ + -o /tmp/docker-credential-pass +``` + +Intel: + +```bash +curl -fsSL "https://github.com/docker/docker-credential-helpers/releases/download/v0.9.5/docker-credential-pass-v0.9.5.darwin-amd64" \ + -o /tmp/docker-credential-pass +``` + +Install: + +```bash +mkdir -p "$HOME/.local/bin" +install -m 0755 /tmp/docker-credential-pass "$HOME/.local/bin/docker-credential-pass" +``` + +If needed: + +```bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zprofile" +export PATH="$HOME/.local/bin:$PATH" +``` + +**Step 3 –** Create the gopass symlinks: + +```bash +ln -sf "$(which gopass)" "$HOME/.local/bin/pass" +``` + +Create the store symlink after gopass initialization in step 6. + +**Step 4 –** Configure Git identity for the local `gopass` store. A remote repository isn't +required: + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +**Step 5 –** Create a GPG key and initialize `gopass`: + +```bash +cat > "$HOME/gpg-batch" <<'EOF' +Key-Type: RSA +Key-Length: 3072 +Subkey-Type: RSA +Subkey-Length: 3072 +Name-Real: Your Name +Name-Email: you@example.com +Expire-Date: 0 +%no-protection +%commit +EOF + +gpg --batch --generate-key "$HOME/gpg-batch" +KEYID="$(gpg --list-secret-keys --with-colons you@example.com | awk -F: '/^sec:/{print $5; exit}')" +gopass --yes init "$KEYID" +``` + +For the standard NPS-D deployment flow, don't add any remote. + +**Step 6 –** Create the store symlink: + +```bash +ln -sfn "${XDG_DATA_HOME:-$HOME/.local/share}/gopass/stores/root" "$HOME/.password-store" +``` + +**Step 7 –** Configure Docker: + +```bash +mkdir -p "$HOME/.docker" +cat > "$HOME/.docker/config.json" <<'EOF' +{ + "credsStore": "pass" +} +EOF +``` + +**Step 8 –** Log in to the NPS-D ECR registry and verify: + +```bash +export REGISTRY="176947481038.dkr.ecr.us-west-2.amazonaws.com" +export REGISTRY_USER="AWS" + +aws ecr get-login-password --region us-west-2 \ + | docker login --username "$REGISTRY_USER" --password-stdin "$REGISTRY" +``` + +```bash +grep -q '"auth"' "$HOME/.docker/config.json" && echo "unexpected inline auth found" +printf '%s' "$REGISTRY" | docker-credential-pass get +``` + +**Step 9 –** Run the validated macOS test harness from the repo root: + +```bash +bash ./scripts/docker-credential-gopass/validate-macos-login.sh +``` + +This validator downloads the official `docker-credential-pass` binary, uses a temporary Docker +config and temporary GPG/gopass home, and confirms that the pre-existing default macOS Docker +config is left untouched afterward. + +**Step 10 –** Validate a passphrase-protected GPG key path: + +```bash +bash ./scripts/docker-credential-gopass/validate-macos-passphrase-login.sh +``` + +This validator uses a passphrase-protected GPG key in a temporary macOS home, runs `docker login`, +primes the `gpg-agent` cache with loopback pinentry, and confirms that helper retrieval succeeds +without modifying the default host Docker config. + +--- + +## Make Targets + +From the repo root: + +```bash +make docker-credential-pass-validate-ubuntu +make docker-credential-pass-validate-all +``` + +--- + +## References + +- [Docker `docker login` documentation](https://docs.docker.com/reference/cli/docker/login/) +- [Docker credential helpers](https://github.com/docker/docker-credential-helpers) +- [`gopass` overview and installation](https://github.com/gopasspw/gopass) +- [`gopass` setup details](https://github.com/gopasspw/gopass/blob/master/docs/setup.md) diff --git a/docs/privilegesecurediscovery/2.22/installation/dockersecrets.md b/docs/privilegesecurediscovery/2.22/installation/dockersecrets.md index 89351d90fd..6edb97affd 100644 --- a/docs/privilegesecurediscovery/2.22/installation/dockersecrets.md +++ b/docs/privilegesecurediscovery/2.22/installation/dockersecrets.md @@ -12,30 +12,30 @@ Docker Secrets Matching DR Site to PROD Site ### Overview -Privilege Secure utilizes Docker secrets to encrypt sensitive data, such as passwords, SSH keys, and +Privilege Secure uses Docker secrets to encrypt sensitive data, such as passwords, SSH keys, and SSL certificates, for transmission over the network. -This secret is created during the installation of Privilege Secure.  To backup and restore data from -one Privilege Secure instance to another, these secrets must match.  Examples of where data would be -required to be transferred data between Privilege Secure instances include: +Privilege Secure creates this secret during installation. To backup and restore data from +one Privilege Secure instance to another, these secrets must match. Examples of when you need to +transfer data between Privilege Secure instances include: - Backing up the database to a disaster recovery instance - Transferring from a single appliance, like a PoC, to a high availability cluster -- Rebuilding the docker swarm for troubleshooting, or  environment restructuring +- Rebuilding the docker swarm for troubleshooting, or environment restructuring -For more information on Docker secrets, please see Docker's page -here:  [Docker: Manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/) +See [Docker: Manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/) +to learn how Docker handles secrets in swarm mode. ### Requirements -This guide utilizes -the [Install the S1 CLI Helper Utility ](./s1clihelperutility.md) +This guide uses +the [Install the S1 CLI Helper Utility ](./s1clihelperutility.md) ### Retrieve the Docker Secret from Current Privilege Secure Instance If using a single appliance, open an SSH session into thePrivilege Secure node. -If using a cluster, located the node running the API service with `s1 status`; and open an SSH +If using a cluster, located the node running the API service with `s1 status`; and open an SSH session into that Privilege Secure node. Run following command: @@ -50,16 +50,16 @@ Check the file was created and has two lines. cat /secureone/data/key.txt; echo ``` -Note:  Without the`; echo` in the command above, the second line will run into the command prompt, -this is expected as that line does not have a carriage return.  +Note: Without the`; echo` in the preceding command, the second line will run into the command prompt, +this is expected as that line doesn't have a carriage return. -Highlight the two lines of the key, stopping at the end of the second line, do not include the +Highlight the two lines of the key, stopping at the end of the second line, don't include the carriage return, and copy. ### Copy Docker Secret to New Privilege Secure Instance -SSH into the primary node of the new instance.  Use your favorite text editor to create a key.txt -file to use for as the new Docker secret.  Vim is used in the below example: +SSH into the primary node of the new instance. Use your favorite text editor to create a key.txt +file to use for as the new Docker secret. The following example uses Vim: ``` sudo vim /secureone/data/key.txt @@ -67,26 +67,27 @@ sudo vim /secureone/data/key.txt Paste the two lines cut from above and save the file. -### Applying the Docker Secret to the New Privilege Secure Instance +### Applying the Docker Secret to the New Privilege Secure Instance -During thePrivilege Secure install, where the Docker secret key is created, instead apply the new -key: +During the Privilege Secure install, at the step that creates the Docker secret key, apply the new +key instead: ``` sudo docker secret create key.txt/secureone/data/key.txt ``` -Continue the deployment.  After the install, you can verify the key was used by following the step -in the 'Retrieve the Docker Secret from Current SecureONE Instance' section at the start of this -article. +Continue the deployment. After the install, verify the new key is in use by following the steps in the 'Retrieve the Docker +Secret from Current SecureONE Instance' section. ### Troubleshooting -Some indicators that the Docker secrets key did not transfer correctly are described in the +Some indicators that the Docker secrets key didn't transfer correctly are described in the Troubleshooting section above. ### More Information [Docker: Manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/) +**See also:** [Docker Credentials Helper](dockercredentials.md) — secure credential storage for +pulling private registry images during NPSD deployment and upgrades. diff --git a/docs/privilegesecurediscovery/2.22/integrations/edr/tanium.md b/docs/privilegesecurediscovery/2.22/integrations/edr/tanium.md new file mode 100644 index 0000000000..e9f51af6b6 --- /dev/null +++ b/docs/privilegesecurediscovery/2.22/integrations/edr/tanium.md @@ -0,0 +1,689 @@ +--- +title: "Tanium" +description: "Tanium" +sidebar_position: 40 +--- + +# Tanium + +## Overview & Architecture + +### Integration Overview + +The Tanium integration enables privileged access management and security scanning of Windows devices +through Tanium's remote execution capabilities. This agentless solution manages local Windows +accounts and gathers security compliance data without requiring direct network connectivity to target +devices. + +### Architecture Diagram + +``` +┌─────────────────┐ API Calls ┌──────────────────┐ +│ │ ───────────────────────────▶│ │ +│ NPS-D │ │ Tanium Cloud │ +│ Platform │◀─────────────────────────── │ Platform │ +│ │ Results │ │ +└─────────────────┘ └──────────────────┘ + │ │ + │ │ + ▼ ▼ +┌─────────────────┐ ┌──────────────────┐ +│ MongoDB │ │ Tanium Agents │ +│ Database │ │ (on endpoints) │ +└─────────────────┘ └──────────────────┘ +``` + +### Supported Use Cases + +| Use Case | Description | Mode | +|---|---|---| +| Privileged Account Discovery | Enumerate local administrator accounts on Windows systems | Scan/Protect | +| Account Lifecycle Management | Create, modify, and delete local Windows accounts | Protect | +| Password Rotation | Automated password changes with RSA encryption | Protect | +| Security Compliance Scanning | Gather system configuration and security posture data | Scan | +| Access Control | Enable/disable local accounts based on policy | Protect | +| Group Membership Management | Add/remove users from local Windows groups | Protect | +| Bulk Scanning | Scan entire computer groups in single operations | Scan | + +### Integration Flow + +#### Standard (single device) flow + +1. Query Tanium to find target device and obtain temporary group ID +2. Create action with PowerShell script and encrypted parameters +3. Monitor action status until completion +4. Retrieve and parse action logs +5. Process results and update NPS-D database + +#### Bulk scan flow + +1. Query Tanium for computer group members +2. Create single action targeting entire group +3. Monitor bulk action completion +4. Parse consolidated results +5. Update all device records in batch + +--- + +## Prerequisites & Requirements + +### NPS-D platform requirements + +- NPS-D 2.22.12, 26.03, or later +- Linux OS (Ubuntu 20.04/22.04 recommended) +- Python 3.9+ +- MongoDB 4.4+ +- Network access to Tanium Cloud API endpoints + +### Tanium requirements + +- Tanium Cloud platform with API v2 access +- Administrator permissions for configuration +- Content Set permissions (Base or custom) +- Ability to create sensors and packages +- Tanium agents deployed on target Windows devices + +### Target device requirements + +- Windows Server 2012 R2 or later +- Windows 10 or later +- PowerShell 5.1 or later +- `Microsoft.PowerShell.LocalAccounts` module +- Tanium agent installed and communicating + +### Required libraries & dependencies + +| Library | Version | Purpose | +|---|---|---| +| requests | 2.28+ | HTTP client for REST API calls | +| pydantic | 1.10+ | Data validation and serialization | +| Cryptodome | 3.15+ | RSA encryption for sensitive data | +| lxml | 4.9+ | XML parsing for Tanium responses | + +--- + +## Part A: Tanium Cloud Setup + +:::warning +A Tanium administrator must perform the following configuration. Complete each step exactly +as specified for the integration to function correctly. +::: + +### Create the NPS Admin Members sensor + +**Step 1 –** Log into the Tanium Cloud Console, go to **Administration** → **Content** → +**Sensors**, and click **Create New Sensor**. + +**Step 2 –** Configure the sensor properties: + +| Property | Value | Notes | +|---|---|---| +| **Name** | `NPS Admin Members` | Must match exactly (case-sensitive) | +| Description | NPS-D Administrator Discovery Sensor | Can be customized | +| Content Set | Base (or custom set) | Choose appropriate content set | +| Category | Security | Recommended for organization | +| **Result Type** | Text | Required setting | +| **Max Sensor Age** | 10 minutes | Minimum recommended by Tanium | +| Max String Age | Disabled or 86400 | Very large value | +| Max Strings | Disabled or 10000 | Very large value | +| Ignore case in results | Disabled | Required setting | +| Hide sensor | Disabled | Must be visible | +| Split into columns | Disabled | Required setting | + +**Step 3 –** Configure the Windows script: + +- Script Type: `PowerShell` +- Script Contents: copy the entire contents from `secureone_management.ps1` (see + [PowerShell Scripts & Packages](#powershell-scripts-packages)) + +**Step 4 –** For other operating systems, set to `Disabled` or return an error message (for +example, `Not available on Linux`). + +**Step 5 –** Click **Preview** on some Windows computers, verify that JSON results appear for most +computers, then click **Save Sensor**. + +### Enable the sensor for background collection + +**Step 1 –** Go to **Modules** → **Interact** → **Overview** → **Settings**. + +**Step 2 –** Find **NPS Admin Members** in the sensor list, click **Actions** → **Add**, preview to +verify JSON results, and click **Confirm**. Optionally click **Collect Now** to force immediate +collection. + +### Create the NPSD Management package + +:::note +You only need this package if you plan to use Protect mode (JITA) or Deny functionality. For +scan-only operations, skip this section. +::: + +**Step 1 –** Go to **Administration** → **Content** → **Packages** and click **Create New +Package**. + +**Step 2 –** Configure the package properties: + +| Property | Value | Notes | +|---|---|---| +| **Package Name** | `NPSD Management` | Must match exactly | +| Display Name | NPS-D Management Package | Can be customized | +| Content Set | Base (or custom) | Same as sensor | +| **Command** | `cmd.exe /d /c powershell.exe -ExecutionPolicy Bypass -WindowStyle Hidden -NonInteractive -NoProfile -File expand_params.ps1 $0` | Critical configuration | +| Command Timeout | 3 minutes | Adjust as needed | +| Download Timeout | 10 minutes | Adjust as needed | +| Ignore Action Lock | Disabled | Default setting | +| Launch in process group | Enabled | Required | + +**Step 3 –** Add the required files to the package: + +- `expand_params.ps1` (see [PowerShell Scripts & Packages](#powershell-scripts-packages)) +- `secureone_management.ps1` (see [PowerShell Scripts & Packages](#powershell-scripts-packages)) + +**Step 4 –** Add a single text parameter with the label `EncodedCommand` and verify the parameter +shows as `$0`. If it shows as `$1`, adjust the command and set `package_param_offset` to `1` in the +NPS-D options. + +**Step 5 –** Review all settings and click **Save Package**. + +### Configure computer groups + +**For standard scanning** — use the existing **All Windows Computers** group, or create custom +groups based on your requirements. + +**For bulk scanning** — identify or create a computer group containing all Windows devices to scan +and note the exact group name for later configuration. Recommended names: `All Windows Computers` +or a custom group such as `NPS-D Managed Devices`. + +### Create API tokens + +**Step 1 –** Go to **Administration** → **Permissions** → **API Tokens** and click **New API +Token**. + +**Step 2 –** Configure the token: + +- **Name:** `NPS-D Integration Token` +- **Permissions:** Full API access (or minimum required) +- **Expiration:** Set according to your security policy + +**Step 3 –** Copy and securely save the API token immediately — it doesn't display again. + +--- + +## Part B: NPS-D Base Integration Setup + +### Enable the Tanium Cloud feature + +Connect to MongoDB and run: + +```bash +mongo + +use npsd + +db.release_toggles.updateOne( + {"name": "tanium_cloud"}, + {$set: {"enabled": true}}, + {upsert: false} +) +``` + +### Configure the EDR provider + +**Step 1 –** In the NPS-D UI, go to **Configure** → **Server** → **EDR Provider Configuration** +and click **Add New**. + +**Step 2 –** Configure the provider settings: + +| Field | Value | Notes | +|---|---|---| +| Provider | Tanium Cloud | Select from dropdown | +| Name | Production Tanium | Descriptive name | +| Enable | Enabled | Check to enable | +| Proxy | (as needed) | Configure if required | +| API Base URL | `https://your-instance.cloud.tanium.com` | From Tanium account | +| API Key | (token from Tanium) | From the API token created above | + +**Step 3 –** Click **Test Connection**, verify the connection is successful, then click **Save**. + +### Configure advanced options + +:::warning +These options must match your Tanium configuration exactly. UI support is planned for a future +release. +::: + +Run the following in MongoDB: + +```javascript +db.integrations_edr_config.updateOne( + {"provider": "tanium_cloud"}, + {$set: { + "config.integration.options": { + // Required — must match Tanium configuration + "sensor_name": "NPS Admin Members", + "sensor_max_age_seconds": 600, + "package_name": "NPSD Management", + "package_param_offset": 0, + + // Recommended optimizations + "action_group_name": "Default - All Computers", + "action_timeout_seconds": 1200, + "action_check_interval_seconds": 1, + + // Bulk scan settings (if using) + "bulk_scan_enabled": false, // Set to true for bulk scan + "bulk_scan_group": "All Windows Computers", + "bulk_scan_batch_size": 100, + "bulk_scan_timeout_seconds": 3600 + } + }} +) +``` + +### Configure computers + +In the NPS-D UI or via the API, configure each computer with the following settings: + +| Setting | Value | Purpose | +|---|---|---| +| Scan | Enabled | For background scanning | +| Protect | Disabled / Enabled | Disabled uses cache; Enabled for real-time | +| Offline Access | Unmanaged | Not supported with Tanium | +| EDR Integration | Production Tanium | Select the configured provider | + +--- + +## Part C: Bulk Scan Configuration + +### Bulk scan overview + +Bulk scanning allows NPS-D to scan all Windows devices in a Tanium computer group with a single API +action, dramatically improving performance for large environments. + +``` +Standard Scan (Sequential): +Device 1 ──▶ Scan ──▶ Result ──┐ + │ +Device 2 ──▶ Scan ──▶ Result ──┼──▶ Total Time: N × scan_time + │ +Device N ──▶ Scan ──▶ Result ──┘ + +Bulk Scan (Parallel): +┌─────────────┐ +│ All Devices │──▶ Single Bulk Action ──▶ All Results ──▶ Total Time: ~scan_time +└─────────────┘ +``` + +### Key benefits + +- **Performance:** 100+ devices scanned in the time it takes to scan one +- **Efficiency:** Single API call instead of hundreds +- **Consistency:** All devices scanned at the same moment +- **Scalability:** Handles thousands of devices efficiently + +### Device inventory mismatch + +:::warning +Device count mismatch between Tanium and NPS-D can impact bulk scan efficiency. +::: + +A common scenario occurs when your Tanium environment contains more Windows devices than are loaded +in NPS-D. + +**Example scenario:** + +- Tanium "All Windows Computers" group: **10,000 devices** +- NPS-D loaded devices: **9,500 devices** +- Result: bulk scan will scan all 10,000 devices but only process results for 9,500 + +**Impact:** + +- Functional impact: none — the scan works correctly +- Performance impact: unnecessary scanning of 500 devices not in NPS-D +- Resource impact: additional Tanium resources used for unneeded scans + +**Recommended solutions:** + +**Option 1: Create a custom Tanium group (recommended)** + +1. In Tanium, create a new computer group: `NPS-D Managed Windows Devices` +2. Include only devices that are loaded in NPS-D +3. Update the bulk scan configuration to use this custom group — this ensures 100% efficiency with + no wasted scans + +**Option 2: Use the default group (acceptable when the performance impact is minimal)** + +1. Continue using the `All Windows Computers` group +2. Accept that extra devices will be scanned but not processed +3. Suitable when the difference is small (less than 5% extra devices) +4. Monitor performance impact and adjust if needed + +To check for a mismatch, compare device counts: + +```bash +# In Tanium Console +Get Computer Name from all machines with Operating System containing "Windows" +# Note the total count +``` + +```javascript +// In NPS-D MongoDB +db.computers.count({"os": /windows/i, "edr_integration": "tanium_cloud"}) +``` + +### Enable bulk scan + +**Step 1 –** Run the following in MongoDB to enable bulk scanning: + +```javascript +db.integrations_edr_config.updateOne( + {"provider": "tanium_cloud"}, + {$set: { + "config.integration.options.bulk_scan_enabled": true, + "config.integration.options.bulk_scan_group": "NPS-D Managed Windows Devices", + "config.integration.options.bulk_scan_batch_size": 100, + "config.integration.options.bulk_scan_timeout_seconds": 3600, + "config.integration.options.bulk_scan_retry_attempts": 2 + }} +) +``` + +**Step 2 –** Bulk scans run automatically as part of the regular `svc_scan` cycle: + +- Executes before individual device scans +- The system removes successfully scanned devices from the individual scan queue +- Devices that fail revert to individual scanning + +### Monitor bulk scans + +**Via the UI dashboard** — go to **Management** → **Bulk Scan Monitor** to view scan progress, +success rate, and failures. + +**Via logs:** + +```bash +# Monitor bulk scan activity +tail -f /var/log/npsd/svc_scan.log | grep "bulk_scan" + +# Check for errors +grep "bulk_scan.*error" /var/log/npsd/svc_scan.log +``` + +**Key metrics to monitor:** + +| Metric | Expected Value | Action if Abnormal | +|---|---|---| +| Success Rate | > 95% | Check Tanium agent health | +| Scan Duration | < 30 minutes | Adjust batch size or timeout | +| API Errors | < 1% | Check API token and network | +| Fallback Count | < 5% | Investigate device issues | + +--- + +## PowerShell Scripts & Packages {#powershell-scripts-packages} + +### secureone_management.ps1 + +:::note +This script is located at: +`/docker/shared/python/src/remediant/integrations/powershell/secureone_management.ps1` +::: + +This is the main PowerShell script that performs all management operations on Windows endpoints. Key +functions include: + +- Local user enumeration and management +- Group membership operations +- Password encryption/decryption +- Admin discovery for bulk scans + +**Key script parameters:** + +```powershell +# Core parameters +-Target # Target type (LocalGroup, LocalUser, General) +-Action # Action to perform (MemberList, SetPassword, etc.) +-SimpleResult # Skip Base64 encoding +-NoMeta # Exclude metadata + +# Group operations +-GroupSID # Target group SID (default: S-1-5-32-544 for Administrators) +-GroupNameB64 # Base64 encoded group name +-MemberSID # Member SIDs for operations + +# User operations +-PropertyKey # User property to modify +-PropertyValuesB64 # Base64 encoded property values +-EncryptedPassword # RSA encrypted password +``` + +### expand_params.ps1 + +:::note +This script is located at: +`/docker/shared/python/src/remediant/integrations/tanium/data/expand_params.ps1` +::: + +This wrapper script decodes the Base64-encoded parameters passed from Tanium and executes the main +management script: + +```powershell +param([string]$EncodedCommand) + +$decodedBytes = [System.Convert]::FromBase64String($EncodedCommand) +$decodedCommand = [System.Text.Encoding]::UTF8.GetString($decodedBytes) + +Invoke-Expression $decodedCommand +``` + +### Deploy scripts to Tanium + +**For the sensor:** + +1. Copy the entire contents of `secureone_management.ps1` +2. Paste into the sensor script field +3. Ensure PowerShell is selected as the script type + +**For the package:** + +1. Upload both `expand_params.ps1` and `secureone_management.ps1` as package files +2. Ensure the command line references the correct file names + +--- + +## Validation & Testing + +### Tanium configuration validation + +**Sensor test:** + +``` +1. Go to Interact +2. Ask Question: "Get NPS Admin Members from all machines" +3. Verify JSON results appear for Windows machines +``` + +**Package test (if using Protect mode):** + +``` +1. Go to Actions → Deploy Action +2. Select "NPSD Management" package +3. Target a test machine +4. Provide test parameter: "Get-Date" +5. Verify action completes successfully +``` + +**API token test:** + +```bash +curl -H "session: token-YOUR_API_TOKEN" \ + https://your-instance.cloud.tanium.com/api/v2/sensors \ + | python -m json.tool +``` + +### NPS-D integration validation + +**Connection test:** + +1. In NPS-D UI: **Configure** → **Server** → **EDR Provider Configuration** +2. Select your Tanium configuration +3. Click **Test Connection** +4. Verify the "Connection Successful" message + +**Single device scan test:** + +```bash +# Via API +curl -X POST https://npsd-server/api/v2/computers/{id}/scan \ + -H "Authorization: Bearer YOUR_TOKEN" + +# Check results +curl https://npsd-server/api/v2/computers/{id} \ + -H "Authorization: Bearer YOUR_TOKEN" | jq .lastScan +``` + +**Bulk scan test:** + +```bash +# Trigger bulk scan +curl -X POST https://npsd-server/api/v2/bulk-scan/trigger \ + -H "Authorization: Bearer YOUR_TOKEN" + +# Monitor progress +curl https://npsd-server/api/v2/bulk-scan/status \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +### End-to-end validation checklist + +| Component | Check | Expected Result | +|---|---|---| +| Tanium Sensor | Query "NPS Admin Members" | JSON results for Windows devices | +| Tanium Package | Deploy test action | Action completes successfully | +| API Token | API call test | 200 OK response | +| NPS-D Connection | Test connection button | Connection successful | +| Single Scan | Scan one device | Admins discovered | +| Bulk Scan | Scan computer group | Multiple devices updated | +| Protect Mode | Grant access test | User added successfully | +| Password Rotation | Rotate password | Password changed | + +--- + +## Troubleshooting + +### Common issues and solutions + +**"Sensor not found" error** + +- **Cause:** Sensor name doesn't match exactly +- **Solution:** Verify the sensor is named exactly `NPS Admin Members` (case-sensitive) +- **Check:** + +```javascript +db.integrations_edr_config.find( + {"provider": "tanium_cloud"}, + {"config.integration.options.sensor_name": 1} +) +``` + +**Bulk scan completes but no devices are updated** + +- **Cause:** Computer group name mismatch or empty group +- **Solution:** Verify the group name in Tanium matches the configuration and that the group + contains Windows devices + +**API timeout errors** + +- **Cause:** Network issues or large result sets +- **Solution:** Increase `action_timeout_seconds` and `bulk_scan_timeout_seconds` in the advanced + options configuration + +**Package parameter error ($0 vs $1)** + +- **Cause:** Tanium UI inconsistency in parameter numbering +- **Solution:** Check the actual parameter number in the package and adjust `package_param_offset` + accordingly + +### Log locations + +| Component | Log Location | Key Information | +|---|---|---| +| Scan Service | `/var/log/npsd/svc_scan.log` | Scan attempts, results, errors | +| Bulk Scan | `/var/log/npsd/bulk_scan.log` | Bulk operation details | +| API Calls | `/var/log/npsd/tanium_api.log` | API requests and responses | +| MongoDB | `/var/log/mongodb/mongod.log` | Database operations | + +### Debug commands + +```bash +# Check feature toggle status +mongo npsd --eval 'db.release_toggles.findOne({"name": "tanium_cloud"})' + +# View EDR configuration +mongo npsd --eval 'db.integrations_edr_config.findOne({"provider": "tanium_cloud"})' + +# Test Tanium API directly +python3 -c " +import requests +headers = {'session': 'token-YOUR_TOKEN'} +r = requests.get('https://your-instance.cloud.tanium.com/api/v2/sensors', headers=headers) +print(r.status_code, r.text[:200]) +" + +# Force immediate scan +docker exec npsd-scanner python -m remediant.scanner.manual_scan --computer-id COMPUTER_ID + +# Check last scan results +mongo npsd --eval 'db.computers.findOne({"_id": "COMPUTER_ID"}, {"lastScan": 1})' +``` + +### Performance tuning + +| Parameter | Default | Recommended Range | Impact | +|---|---|---|---| +| sensor_max_age_seconds | 600 | 300–1800 | Freshness vs. API load | +| action_timeout_seconds | 1200 | 600–3600 | Reliability vs. speed | +| bulk_scan_batch_size | 100 | 50–500 | Memory vs. efficiency | +| action_check_interval_seconds | 1 | 1–5 | Responsiveness vs. API calls | + +--- + +## API Reference & Technical Details + +### REST API endpoints + +| Endpoint | Method | Purpose | +|---|---|---| +| `/api/v2/questions` | POST | Device discovery and queries | +| `/api/v2/actions` | POST | Create management actions | +| `/api/v2/actions/{id}` | GET | Monitor action status | +| `/api/v2/packages` | GET/POST | Package management | +| `/api/v2/sensors` | GET/POST | Sensor configuration | +| `/api/v2/result_data/*` | GET | Retrieve action results | +| `/api/v2/groups` | GET | Computer group information | + +### Key Python files + +| File Path | Purpose | +|---|---| +| `/remediant/windows/connector/strategies/tanium/strategy.py` | Main strategy implementation | +| `/remediant/windows/connector/strategies/tanium/session.py` | API session management | +| `/remediant/integrations/tanium/api/api_calls.py` | REST API client | +| `/remediant/integrations/tanium/bulk_scan.py` | Bulk scan implementation | + +### Database collections + +| Collection | Key Documents | Purpose | +|---|---|---| +| release_toggles | `{"name": "tanium_cloud"}` | Feature enablement | +| integrations_edr_config | `{"provider": "tanium_cloud"}` | Integration configuration | +| computers | All managed devices | Device records and scan results | +| bulk_scan_history | Bulk scan records | Historical scan data | + +### Security considerations + +- NPS-D encrypts API tokens at rest using AES-256 +- Passwords use session-specific RSA key pairs (2048-bit) +- All API communications use TLS 1.2+ +- NPS-D automatically cleans up temporary files +- NPS-D doesn't log sensitive data in plain text +- NPS-D supports HTTP proxy with authentication diff --git a/src/theme/EditThisPage/index.js b/src/theme/EditThisPage/index.js new file mode 100644 index 0000000000..1e6ab4a63a --- /dev/null +++ b/src/theme/EditThisPage/index.js @@ -0,0 +1,34 @@ +import React from 'react'; +import {useLocation} from '@docusaurus/router'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import {ThemeClassNames} from '@docusaurus/theme-common'; +import Link from '@docusaurus/Link'; +import IconEdit from '@theme/Icon/Edit'; + +const GITHUB_ISSUES_URL = 'https://github.com/netwrix/docs/issues/new'; + +export default function EditThisPage({editUrl}) { + const location = useLocation(); + const {siteConfig} = useDocusaurusContext(); + + const pageUrl = `${siteConfig.url}${location.pathname}`; + const title = `Feedback: ${pageUrl}`; + const body = `**Page:** ${pageUrl}\n\n**Issue or question:**\n\n`; + + const issueUrl = + GITHUB_ISSUES_URL + + '?labels=' + encodeURIComponent('documentation,fix') + + '&title=' + encodeURIComponent(title) + + '&body=' + encodeURIComponent(body); + + return ( + + + Ask questions or request changes + + ); +}