> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CyberArk

This guide walks you through connecting your CyberArk Privileged Access Management (PAM) platform to TruU TOTAL for persona generation and threat detection.

***

## Overview

TOTAL ingests privileged session and vault activity events from CyberArk via the CyberArk REST API and SIEM integration endpoints. We poll the audit log and session monitoring APIs on a configurable interval to collect, normalize, and correlate privileged account usage, session recordings metadata, credential checkouts, and vault administration events.

**Connector Type:** Polling

***

## Prerequisites

* **CyberArk Privilege Cloud** or **CyberArk PAM Self-Hosted** (v12.0+) with REST API enabled
* **Vault Administrator** or **Auditor** role with API access
* For Privilege Cloud: **Secure Tunnel** deployed and operational
* For Self-Hosted: Network connectivity from TOTAL to the PVWA (Password Vault Web Access) server
* Approximately **20 minutes** to complete setup

***

## Step 1: Identify Your CyberArk Instance

### Privilege Cloud

Your CyberArk Privilege Cloud URL follows the format:

```
https://your-company.privilegecloud.cyberark.cloud
```

### Self-Hosted

Your PVWA URL follows the format:

```
https://pvwa.your-company.com/PasswordVault
```

Paste the appropriate URL into the TruU Portal.

***

## Step 2: Create a Dedicated API User

### Privilege Cloud

1. Sign in to the CyberArk Identity Administration portal
2. Navigate to **Users** → **Add User**
3. Enter:
   * **Username**: `truu-total-integration`
   * **Authentication Method**: OAuth2 / OIDC (recommended) or CyberArk
4. Assign the user to the **Auditors** group (or a custom group with read-only vault and audit permissions)
5. Save the user

### Self-Hosted

1. Log in to the PVWA
2. Navigate to **Administration** → **Users & Groups**
3. Click **Add User**
4. Enter:
   * **Username**: `truu-total-integration`
   * **Authentication Method**: CyberArk or LDAP
5. Assign the following authorizations:
   * **Audit Users** — read audit logs
   * **List Accounts** — read account inventory
   * **View Audit** — view session recordings metadata
6. Save the user

***

## Step 3: Configure API Access

### Privilege Cloud (OAuth 2.0)

1. In CyberArk Identity Administration, navigate to **Settings** → **OAuth 2.0**
2. Register a new OAuth 2.0 client:
   * **Client Name**: `TruU TOTAL Integration`
   * **Grant Type**: Client Credentials
   * **Scopes**: `audit`, `accounts` (read-only)
3. Copy the **Client ID** and **Client Secret**
4. Paste them into the TruU Portal

### Self-Hosted (API Key / Session Token)

1. TOTAL will authenticate using the service account credentials via the CyberArk Logon API (`/api/auth/cyberark/logon`)
2. Enter the **Username** and **Password** in the TruU Portal
3. TOTAL will manage session tokens automatically

***

## Step 4: Verify Connectivity

Once credentials are entered in the TruU Portal:

1. Click **Test Connection** — TOTAL will authenticate and query the audit log endpoint
2. If successful, you'll see a confirmation with recent privileged session events detected
3. If configured, TOTAL will run a historical data pull (up to 7 days) to seed user personas

***

## Security & Privacy

### What We Access

* **Read-only access** to CyberArk audit logs and session metadata via REST API
* Privileged session start/end events, credential checkout/checkin events, and vault administration audit trail
* All queries use timestamp filtering — we only fetch new events since the last poll

### What We Don't Have Access To

* Stored passwords or credentials in the vault
* Ability to check out, modify, or rotate credentials
* Session recording video content (only metadata)
* Vault configuration or policy management
* Safe management or account provisioning

***

## Updating or Rotating Credentials

### Rotate Credentials

1. In CyberArk Identity Administration (Privilege Cloud) or PVWA (Self-Hosted), update the `truu-total-integration` user credentials
2. For OAuth 2.0: Generate a new client secret and update it in the TruU Portal
3. For session-based: Update the password in the TruU Portal
4. Click **Test Connection** to verify

### Revoke Access

To immediately remove TOTAL's access:

1. **Option A** — Disable in the TruU Portal
2. **Option B** — Disable the `truu-total-integration` user in CyberArk
3. **Option C** — Delete the API user or revoke the OAuth 2.0 client

***

## Rate Limiting & Scalability

### CyberArk API Rate Limits

| Parameter                  | Limit                                                                |
| -------------------------- | -------------------------------------------------------------------- |
| **Throttling model**       | Dynamic — based on PVWA CPU usage + request queue depth              |
| **Throttle triggers**      | CPU > 90% and avg requests per processor > 8 (both must be exceeded) |
| **SIEM API event window**  | Last 7 days of audit events                                          |
| **Practical request rate** | \~5–15 req/s under normal PVWA load                                  |

### Ingestion Capacity

PAM events are inherently moderate-volume. A large enterprise with 100K+ users and 5K–20K privileged accounts typically generates 15K–150K CyberArk events/day. At 5–15 req/s practical throughput, TOTAL has significant headroom. CyberArk's dynamic throttling ensures the PVWA always prioritizes interactive privileged sessions over API consumers — TOTAL adapts its request pacing to stay well below the throttle threshold.

### Event Freshness

Events appear in the CyberArk audit log within seconds. TOTAL polls on a configurable interval (default: 2 minutes). End-to-end latency is typically **under 5 minutes**.

### Resilience

TOTAL uses cursor-based ingestion with at-least-once delivery. The polling cursor only advances after events are successfully collected, normalized, and published. If any step fails, the cursor stays put and the next poll replays from the last known-good position. No events are lost.

Transient failures (throttling, 5xx, timeouts) are retried automatically with exponential backoff. After 5 consecutive failures, the connector self-pauses and can be re-enabled from the TruU Portal. The CyberArk SIEM API retains 7 days of audit events, so any outage shorter than that results in zero data loss.

### Connector Design

Each connector polls on an independent, configurable interval. Events are batched and published in per-user order to preserve sequence integrity for persona building. Connector workers are stateless and scale horizontally. All polling intervals, page sizes, and batching parameters are tunable from the TruU Portal.

***

# Part 2: Event Types & Data Schema

## Signal Classification

| Signal Class            | TOTAL Category                  |
| ----------------------- | ------------------------------- |
| Privileged Access (PAM) | Authentication, Admin, Endpoint |

## Event Types We Ingest

TOTAL extracts the following categories of events from CyberArk. Every event is tied to a human identity — the user who initiated the privileged session, retrieved the credential, or performed the vault action. Automated CPM (Central Policy Manager) events are excluded since they are machine-initiated.

### Privileged Session Events

| CyberArk Audit Code | Event                             | Description                                      | TOTAL Classification |
| ------------------- | --------------------------------- | ------------------------------------------------ | -------------------- |
| 300                 | `PSM Connect`                     | Privileged session initiated via PSM             | Authentication       |
| 301                 | `PSM Disconnect`                  | Privileged session terminated                    | Authentication       |
| 302                 | `PSM Session Duration`            | Session duration recorded                        | Authentication       |
| 303                 | `PSM Keystroke Logging`           | Keystroke activity metadata captured             | Endpoint             |
| 304                 | `PSM Command Executed`            | Command executed in privileged session (SSH/CLI) | Endpoint             |
| 305                 | `PSM File Transfer`               | File transferred during privileged session       | Data Access          |
| 306                 | `PSM Window Title Changed`        | Application window changed during RDP session    | Endpoint             |
| 307                 | `PSM Session Suspended`           | Privileged session suspended                     | Authentication       |
| 308                 | `PSM Session Resumed`             | Privileged session resumed                       | Authentication       |
| 309                 | `PSM Session Terminated by Admin` | Session forcefully terminated by admin           | Admin                |

### Credential Vault Events

| CyberArk Audit Code | Event               | Description                                 | TOTAL Classification |
| ------------------- | ------------------- | ------------------------------------------- | -------------------- |
| 22                  | `Retrieve Password` | Password retrieved (checked out) from vault | Authentication       |
| 24                  | `Password Used`     | Retrieved password was used to connect      | Authentication       |
| 51                  | `Store Password`    | User stored a new password in vault         | Admin                |
| 52                  | `Delete Password`   | User deleted a password from vault          | Admin                |
| 57                  | `Copy Password`     | Password copied to clipboard                | Authentication       |
| 60                  | `Retrieve File`     | File retrieved from vault                   | Data Access          |
| 61                  | `Store File`        | File stored in vault                        | Admin                |

### User & Access Events

| CyberArk Audit Code | Event                       | Description                          | TOTAL Classification |
| ------------------- | --------------------------- | ------------------------------------ | -------------------- |
| 4                   | `Logon`                     | User authenticated to CyberArk vault | Authentication       |
| 5                   | `Logon Failed`              | Failed authentication attempt        | Authentication       |
| 6                   | `Logoff`                    | User logged off from vault           | Authentication       |
| 7                   | `User Created`              | New vault user created               | Admin                |
| 8                   | `User Deleted`              | Vault user deleted                   | Admin                |
| 9                   | `User Updated`              | Vault user properties modified       | Admin                |
| 10                  | `Group Created`             | Vault group created                  | Admin                |
| 11                  | `Group Deleted`             | Vault group deleted                  | Admin                |
| 12                  | `Member Added to Group`     | User added to vault group            | Admin                |
| 13                  | `Member Removed from Group` | User removed from vault group        | Admin                |

### Safe Membership Events

| CyberArk Audit Code | Event                 | Description                      | TOTAL Classification |
| ------------------- | --------------------- | -------------------------------- | -------------------- |
| 16                  | `Safe Member Added`   | User added as member to a safe   | Admin                |
| 17                  | `Safe Member Removed` | User removed from a safe         | Admin                |
| 18                  | `Safe Member Updated` | User's safe permissions modified | Admin                |

### JIT (Just-In-Time) Access Events

| CyberArk Event         | Description                           | TOTAL Classification |
| ---------------------- | ------------------------------------- | -------------------- |
| `JIT Access Requested` | Just-in-time access request submitted | Access               |
| `JIT Access Granted`   | JIT access approved and activated     | Access               |
| `JIT Access Expired`   | JIT access window expired             | Access               |
| `JIT Access Revoked`   | JIT access manually revoked           | Access               |

***

## Sample Source Event (CyberArk Audit Log — Password Retrieval)

```json theme={null}
{
  "AuditCode": 22,
  "Action": "Retrieve Password",
  "User": "jane.doe@acme.com",
  "SourceAddress": "10.0.1.45",
  "Safe": "AWS-Production-Admins",
  "Object": "aws-root-account",
  "Reason": "Emergency maintenance - ticket INC-2026-0451",
  "RequestId": "req-001",
  "Timestamp": "2026-03-15T02:15:30.000Z",
  "SessionId": "sess-001",
  "GatewayAccount": "PSM-Gateway-01",
  "TargetAddress": "console.aws.amazon.com",
  "Protocol": "HTTPS",
  "Database": "",
  "Platform": "AWS",
  "DeviceType": "Operating System",
  "AdditionalInfo": {
    "DualControl": true,
    "DualControlRequestConfirmedBy": "john.manager@acme.com",
    "TicketId": "INC-2026-0451",
    "ConnectionComponent": "PSM-RDP",
    "IsExclusive": false
  }
}
```

## TOTAL Normalized Event

```json theme={null}
{
  "event_id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
  "event_type": "AUTH",
  "source": "CYBERARK",
  "signal_type": "PAM",
  "domain_id": "customer-domain-001",
  "tuid": "tuid-jane-doe-001",
  "timestamp": "2026-03-15T02:15:30.000Z",
  "payload": {
    "user": "jane.doe@acme.com",
    "action": "Retrieve Password",
    "safe": "AWS-Production-Admins",
    "account": "aws-root-account",
    "target": "console.aws.amazon.com",
    "protocol": "HTTPS",
    "platform": "AWS",
    "reason": "Emergency maintenance - ticket INC-2026-0451",
    "dual_control": true,
    "approved_by": "john.manager@acme.com"
  },
  "raw_metadata": {
    "platform_event_id": "req-001",
    "audit_code": 22,
    "action": "Retrieve Password",
    "user": "jane.doe@acme.com",
    "source_address": "10.0.1.45",
    "safe": "AWS-Production-Admins",
    "object": "aws-root-account",
    "reason": "Emergency maintenance - ticket INC-2026-0451",
    "session_id": "sess-001",
    "gateway_account": "PSM-Gateway-01",
    "target_address": "console.aws.amazon.com",
    "protocol": "HTTPS",
    "platform": "AWS",
    "dual_control": true,
    "dual_control_confirmed_by": "john.manager@acme.com",
    "ticket_id": "INC-2026-0451",
    "connection_component": "PSM-RDP",
    "is_exclusive": false,
    "created_at": "2026-03-15T02:15:30.000Z",
    "source_platform": "cyberark"
  },
  "platform_event_id": "req-001",
  "platform_event_source": "CYBERARK_VAULT_API"
}
```

***

## How This Feeds TOTAL

### Persona Building

CyberArk events define a user's **privileged access profile** — which safes they access, what credentials they check out, when they initiate privileged sessions, and what targets they connect to. This forms the privileged layer of each persona, establishing expected privileged workflows and separating normal administrative behavior from anomalous activity.

### Anomaly Detection

TOTAL's behavioral engine uses CyberArk events to detect:

* **Anomalous privileged sessions** — credential checkouts at unusual times, for unusual targets, or from unusual source IPs
* **Privilege escalation indicators** — users accessing safes or credentials outside their historical pattern
* **Session anomalies** — unusually long sessions, sessions terminated by admin (indicating suspicious activity), or sessions with unusual command patterns
* **Credential misuse** — password retrievals without corresponding session activity, or retrievals that bypass dual-control workflows
* **Vault administration anomalies** — unexpected safe creation, member additions, or permission changes that expand privileged access
* **JIT access abuse** — frequent JIT requests, requests outside normal hours, or requests for credentials not aligned with the user's role

### Breach Lifecycle Coverage

CyberArk events provide primary coverage across **Privilege Escalation** and **Siege** stages. By monitoring real-time use of privileged identities, TOTAL detects when an attacker has obtained elevated access and is actively using it — the critical window between privilege escalation and material impact. When correlated with upstream identity and communication signals, PAM events provide high-confidence confirmation of active threat.