diff --git a/docs/accessanalyzer/2601/configurations/_category_.json b/docs/accessanalyzer/2601/configurations/_category_.json new file mode 100644 index 0000000000..e493e2c253 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Configuration", + "position": 16, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/configurations/activity-monitor-integration.md b/docs/accessanalyzer/2601/configurations/activity-monitor-integration.md new file mode 100644 index 0000000000..6991fdb245 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/activity-monitor-integration.md @@ -0,0 +1,308 @@ +--- +title: "Activity Monitor Integration" +description: "Configure Netwrix Activity Monitor to stream real-time file system, SharePoint, and Copilot activity events into Access Analyzer" +sidebar_position: 85 +--- + +# Activity Monitor Integration + +## Overview + +Access Analyzer integrates with **Netwrix Activity Monitor (NAM)** to ingest real-time file system, SharePoint Online, and Microsoft 365 Copilot activity events. Once configured, these events populate the activity reports in AA2601 and power anomaly detection and sensitive data activity tracking. + +The integration works through a built-in TCP listener that NAM agents connect to over a secure, mutually authenticated TLS 1.3 channel. Events stream continuously from NAM agents into AA2601's analytics database (ClickHouse), where they become available in reports. + +### Architecture + +``` +NAM Agent(s) + │ + │ TLS 1.3 (default port 1514) + │ mTLS — client certificate required + ▼ +AA2601 NAM Listener (core-api) + │ + │ Validated & buffered in memory + ▼ +ClickHouse (analytics database) + │ + ▼ +AA2601 Reports (file system activity, SharePoint, Copilot) +``` + +### Event Types + +| Event Type | Content | +| --- | --- | +| **File System Events** | SMB/CIFS file access, reads, writes, renames, permission changes — path, user, bytes transferred | +| **SharePoint Online Events** | SharePoint file and folder activity — user, site, event type | +| **LEEF Events** | Network-format events — vendor, product, source/destination IP, signatures | +| **Copilot Events** | Microsoft 365 Copilot interactions — user, entity, workload, region | + +### Security Model + +Authentication uses **mutual TLS with SPKI hash pinning**: + +- AA2601 requires TLS 1.3 — no older protocol versions are accepted. +- NAM agents must present a client certificate on every connection. +- Certificate chain validation is intentionally permissive — NAM agents use self-signed certificates. +- Real agent authentication is performed by matching the SHA-256 hash of the agent's certificate public key (SPKI hash) against a persistent allowlist in AA2601's database. + +SPKI hashes survive certificate renewal as long as the key pair is unchanged. Re-enrollment is only required when an agent generates a new key pair. + +--- + +## Prerequisites + +Before connecting NAM agents to AA2601: + +- **Netwrix Activity Monitor** must be installed and monitoring the hosts for which you want real-time activity in AA2601. Confirm monitoring is active before adding the AA2601 output. +- **TLS certificates** must be provisioned on the AA2601 server. The server certificate and private key paths are set via the environment variables `SYSLOG_TLS_CERT_PATH` and `SYSLOG_TLS_KEY_PATH`. Contact your infrastructure team if the listener is not starting. +- **Network connectivity** must allow NAM agents to reach AA2601 on TCP port 1514 (default) through any firewalls or network policies. +- You must have **Administrator** access to AA2601 to generate enrollment tokens and view enrolled agents. + +:::note +Activity data flows from NAM to AA2601 — AA2601 does not initiate the connection. Ensure firewalls allow outbound traffic from each NAM agent host to the AA2601 server on the configured listener port. +::: + +--- + +## Setup + +### Step 1 — Verify the Listener Is Running + +The listener starts automatically when AA2601 starts, provided TLS certificates are present and the `enable_activitymonitor_ingestion` feature flag is enabled (it is by default). + +To confirm it is active: + +1. Go to **Configuration > Application Settings > Feature Flags**. +2. Verify `enable_activitymonitor_ingestion` is set to `true`. + +If the listener is not running, check the application logs for the reason — missing certificate, disabled feature flag, or a startup error. + +### Step 2 — Generate an Enrollment Token + +1. Go to **Configuration > Application Settings**. +2. Scroll to the **Activity Monitor** section. +3. Under **Enrollment Token**, click **Generate Token**. +4. Copy the token using the clipboard icon. + +:::note +Tokens expire after **1 hour**. Generating a new token immediately invalidates any previously issued token. A single token can enroll multiple agents simultaneously — plan your enrollment session and generate the token immediately before you begin. +::: + +### Step 3 — Add the AA2601 Output in Netwrix Activity Monitor + +Add an AA2601 output destination to each monitoring policy in NAM that covers the hosts you want to stream into AA2601. + +:::note +The following steps describe the general configuration flow. Exact menu labels and field names in the NAM console may differ depending on your NAM version. Verify the steps against the NAM documentation for your installed version. +::: + +1. Open the Netwrix Activity Monitor console. +2. Navigate to the monitoring policy for the target host or host group. +3. Open the output configuration for that policy. +4. Add a new output destination and select the **Netwrix Access Analyzer** output type. +5. Enter the hostname or IP address of your AA2601 instance and the listener port (default: 1514). +6. When prompted for an enrollment token, enter the token you generated in Step 2. +7. Save the output configuration. +8. Repeat for each monitoring policy covering additional hosts. + +The NAM agent connects to AA2601, presents its client certificate, and sends an enrollment request. AA2601 validates the token, adds the agent's SPKI hash to the trusted agents allowlist, and confirms enrollment. After that, the agent reconnects and begins streaming events. The enrollment token is no longer needed unless the agent generates a new key pair. + +### Step 4 — Verify Enrollment + +After enrollment, the agent appears in AA2601's trusted agents list. You can view enrolled agents via the API: + +``` +GET /api/v1/nam-listener/agents +``` + +Each entry shows the agent's hostname, source IP, and enrollment timestamp. + +To confirm AA2601 is receiving events: + +1. Log in to Access Analyzer. +2. Navigate to the resource or host that NAM is monitoring. +3. Review the activity data for recent file events. + +If no events appear after a few minutes, see [Troubleshooting](#troubleshooting) below. + +--- + +## Application Settings Reference + +All Activity Monitor settings are at **Configuration > Application Settings > Activity Monitor**. Settings take effect immediately when saved — no restart required. Each setting shows its current value, default, and an **Overridden** badge when changed from the default. Use the reset (↺) button to restore an individual setting to its default. + +### Connection Settings + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| `activitymonitor_tcp_port` | 1514 | 1 – 65535 | TCP port the listener binds to. Must match the port configured in NAM agent settings. | +| `activitymonitor_max_connections` | 100 | 10 – 1000 | Maximum simultaneous agent connections. Connections beyond this limit are rejected at the TCP layer. | +| `activitymonitor_connection_timeout` | 900 | 5 – 3600 | Seconds of inactivity before an idle agent connection is dropped. Set this to be comfortably longer than your NAM polling interval. | + +### Performance and Throughput Settings + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| `activitymonitor_reactor_threads` | 0 (auto) | 0 – 32 | Async I/O threads for handling connections. `0` automatically uses one thread per CPU core — correct for almost all deployments. | +| `activitymonitor_buffer_threads` | 8 | 1 – 16 | Writer threads that drain the in-memory event buffer to ClickHouse. More threads help sustain high write rates. | +| `activitymonitor_buffer_max_size` | 10,000 | 1,000 – 500,000 | Maximum events held in memory at once. When full, new arrivals are held at the TCP layer (backpressure to agents) rather than dropped. | +| `activitymonitor_batch_size` | 100 | 10 – 1,000 | Events grouped per internal processing batch. | +| `activitymonitor_batch_interval_seconds` | 10 | 1 – 60 | Maximum seconds between batch flushes to ClickHouse. The primary control for **data freshness** — lower values mean events appear in reports sooner, at the cost of more frequent small writes. | +| `activitymonitor_clickhouse_batch_size` | 10,000 | 1,000 – 100,000 | Events per ClickHouse write operation. Larger batches are more efficient but increase memory usage during the write. | +| `activitymonitor_max_concurrent_jobs` | 3 | 1 – 10 | Maximum parallel batch processing jobs. | + +### Security and Enrollment Settings + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| `activitymonitor_enrollment_first_message_timeout_seconds` | 10 | 5 – 60 | Seconds AA2601 waits for the first message after a new connection is established. Connections that send nothing within this window are closed. | +| `activitymonitor_enrollment_ban_duration_seconds` | 10 | 5 – 300 | Seconds a source IP is blocked after a protocol violation (invalid enrollment code, malformed JSON, or unexpected message format). | +| `activitymonitor_max_message_size` | 16,777,216 (16 MB) | 65,536 – 67,108,864 | Maximum byte size of a single message from a NAM agent. If exceeded without a line delimiter, the connection is dropped. | + +### Shutdown Settings + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| `activitymonitor_shutdown_drain_timeout_seconds` | 300 | 10 – 3,600 | Maximum seconds AA2601 waits for buffered events to finish writing to ClickHouse during a graceful shutdown. After this window, remaining writer threads are force-terminated and events still in the buffer are lost. | + +--- + +## Best Practices + +### Port Configuration + +Use the default port (1514) unless you have a conflict. If you must change it: + +- Update NAM agent configuration to match **before** saving the new port in AA2601. +- Update firewall rules and network policies before making the change. +- Changing the port requires all currently connected agents to reconnect. + +### TLS Certificate Management + +- **Monitor certificate expiration.** AA2601 logs a warning when the server certificate is within 30 days of expiry, and again within 7 days. Treat the 30-day warning as actionable. +- **NAM agents use self-signed certificates** — this is expected and supported. Do not replace them with CA-signed certificates unless your NAM deployment specifically requires it. +- **Key pair rotation requires re-enrollment.** If a NAM agent generates a new key pair (for example, after a reinstall), its previous SPKI hash entry will no longer match. Re-enroll the agent using a new enrollment token. Remove the stale entry via the API: `DELETE /api/v1/nam-listener/agents/:spki_hash`. + +### Enrollment Token Practices + +- **Generate the token immediately before enrollment.** The 1-hour window is intentionally short. +- **Do not share tokens in email or chat.** Treat enrollment tokens like temporary passwords — use a secure transfer method. +- **For bulk enrollment**, all agents can use the same token as long as they enroll within the 1-hour window. +- **Revoke stale entries** when decommissioning a NAM agent host. An enrolled agent with a stale SPKI entry poses no security risk, but maintaining a clean allowlist helps with auditing. + +### Performance Tuning + +Start with defaults. Only adjust if you observe specific symptoms. + +**If events appear in reports with high latency (> 30 seconds):** +- Lower `activitymonitor_batch_interval_seconds` (for example, from 10 to 5). +- Check `activitymonitor_buffer_max_size` — if the buffer is routinely full, ClickHouse writes may be the bottleneck. + +**If you have a high-volume environment (many agents, high event rate):** +- Increase `activitymonitor_buffer_max_size` to 50,000 – 100,000 to absorb burst traffic. +- Increase `activitymonitor_clickhouse_batch_size` to 25,000 – 50,000 to reduce write frequency. +- Increase `activitymonitor_buffer_threads` to 12 – 16 to parallelize writes. +- Leave `activitymonitor_reactor_threads` at `0` (auto). + +**If you have many agents connecting simultaneously:** +- Raise `activitymonitor_max_connections` to at least the number of expected concurrent agents, with 20–30% headroom. + +**Do not lower `activitymonitor_connection_timeout` below your NAM polling interval.** If NAM sends events every 5 minutes and the timeout is less than 300 seconds, agents will be dropped between batches and forced to reconnect constantly. The default of 900 seconds provides safe headroom for most polling configurations. + +### Kubernetes Shutdown Considerations + +The `activitymonitor_shutdown_drain_timeout_seconds` setting (default: 300 seconds) controls how long AA2601 waits during graceful shutdown to flush buffered events to ClickHouse. + +In Kubernetes deployments, the pod's `terminationGracePeriodSeconds` must be greater than this value plus a small buffer for the rest of the shutdown sequence. If `terminationGracePeriodSeconds` is less than the drain timeout, Kubernetes will force-kill the pod before drain completes and buffered events will be lost. + +### Disabling the Integration + +To temporarily disable ingestion without removing agent configurations: + +1. Go to **Configuration > Application Settings > Feature Flags**. +2. Set `enable_activitymonitor_ingestion` to `false` and save. + +The listener stops accepting new connections. Existing agents will see their connections close and queue events locally per NAM's own buffering. When you re-enable ingestion, agents reconnect and resume streaming. + +:::note +Disabling and re-enabling does not cause data loss for events that occurred while disabled, as long as NAM agents have sufficient local buffering. +::: + +--- + +## Troubleshooting + +### The listener is not starting + +- Verify `enable_activitymonitor_ingestion` is `true` in **Configuration > Application Settings > Feature Flags**. +- Verify the TLS certificate environment variables (`SYSLOG_TLS_CERT_PATH`, `SYSLOG_TLS_KEY_PATH`) are set and the files are readable. The application logs report a specific error if a certificate is missing, unreadable, or expired. +- Verify the configured port is not already bound by another process. + +The listener retries startup up to 5 times with exponential backoff (starting at 0.5s, capping at 30s). Check logs for `"Failed to start NAM Listener"` messages with retry counts. + +### A NAM agent cannot connect + +- Verify network connectivity from the agent host to AA2601 on the configured port (default: 1514). +- Verify the agent is configured with the correct hostname and port. The port in NAM agent configuration must match `activitymonitor_tcp_port`. +- Verify the agent has a valid TLS client certificate. Connections without a client certificate are rejected and the source IP is temporarily banned. + +### An agent connected but is not sending data + +- Verify the agent was successfully enrolled. An agent that has not completed enrollment is silently rejected on data connections because its SPKI hash is not in the allowlist. Re-enroll using a new token. +- Verify `activitymonitor_connection_timeout` is not shorter than the agent's event polling interval. If agents idle longer than the timeout, they are dropped between batches and must reconnect. + +### Events are not appearing in reports + +- Verify ClickHouse is healthy and reachable from AA2601. Writer threads log errors if ClickHouse writes fail. +- Check `activitymonitor_batch_interval_seconds` — at the default of 10 seconds, there is a short delay between an event occurring and appearing in a report. +- Check application logs for buffer queue depth statistics. If the buffer is full, ClickHouse writes may be lagging — consider increasing `activitymonitor_buffer_max_size` or `activitymonitor_clickhouse_batch_size`. + +### An agent keeps getting banned + +Repeated IP bans (governed by `activitymonitor_enrollment_ban_duration_seconds`) are triggered by protocol violations: invalid enrollment codes, malformed JSON, or unexpected message formats. + +- Verify the agent is sending the correct enrollment payload. The agent should be a supported Netwrix Activity Monitor version. +- Verify the enrollment token has not expired (1-hour TTL). An expired token causes an invalid-code rejection and a short ban. Generate a new token and retry. + +Bans are short (default: 10 seconds) and reset on pod restart. For persistent issues, check NAM agent logs for the specific error response AA2601 sends during enrollment. + +### Enrolled agents list has stale entries + +Agents that have been decommissioned or reinstalled may leave stale entries in the allowlist. These are harmless — the old SPKI hash will never match a new agent's certificate. Remove them using the API: + +``` +DELETE /api/v1/nam-listener/agents/:spki_hash +``` + +List all enrolled agents at: + +``` +GET /api/v1/nam-listener/agents +``` + +--- + +## Settings Quick Reference + +| Scenario | Setting | Recommended Change | +| --- | --- | --- | +| High event volume | `activitymonitor_buffer_max_size` | Increase to 50,000 – 100,000 | +| High event volume | `activitymonitor_clickhouse_batch_size` | Increase to 25,000 – 50,000 | +| High event volume | `activitymonitor_buffer_threads` | Increase to 12 – 16 | +| Many agents (> 100) | `activitymonitor_max_connections` | Set to agent count + 30% headroom | +| Improve report freshness | `activitymonitor_batch_interval_seconds` | Decrease to 3 – 5 | +| Long agent idle intervals | `activitymonitor_connection_timeout` | Increase to 1800 – 3600 | +| Kubernetes slow shutdown | `activitymonitor_shutdown_drain_timeout_seconds` | Decrease; align `terminationGracePeriodSeconds` | +| Maintenance window | `enable_activitymonitor_ingestion` | Set to `false`, re-enable when done | +| Port conflict | `activitymonitor_tcp_port` | Change to available port; update NAM agents and firewall rules first | + +--- + +## Related Resources + +- [Netwrix Activity Monitor Documentation](https://docs.netwrix.com/docs/activitymonitor) +- [Hardware and System Requirements](/docs/accessanalyzer/2601/install/system/requirements) +- [Network and Port Requirements](/docs/accessanalyzer/2601/install/system/network) diff --git a/docs/accessanalyzer/2601/configurations/application-settings.md b/docs/accessanalyzer/2601/configurations/application-settings.md new file mode 100644 index 0000000000..b52fc75ff3 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/application-settings.md @@ -0,0 +1,106 @@ +--- +title: "Application Settings" +description: "Managing application settings in the Configuration node" +sidebar_position: 80 +--- + +# Application Settings + +The Application Settings page exposes configurable options that control scan behavior, file scanning limits, feature availability, Activity Monitor integration, and application branding. Navigate to **Configuration** > **Application Settings** to view and modify these settings. + +:::note +This page is available to users with the **Administrator** role only. +::: + +## Setting categories + +| Category | What it controls | +| --- | --- | +| **Feature Flags** | Enable or disable product features and integrations | +| **Scanning** | Execution history retention for scans and identity syncs | +| **File Scanning** | File size limits and excluded extensions for SMB and SharePoint scans | +| **Activity Monitor** | TCP listener behavior and enrollment token for NAM agent connections | +| **Branding** | Company name and support email displayed in the application | + +## Feature Flags + +Feature flags enable or disable specific product capabilities. Changes take effect immediately — no restart required. + +| Flag | Default | Description | +| --- | --- | --- | +| **MIP Labeling** | Enabled | Enables Microsoft Information Protection (MIP) sensitivity label management for SMB file shares and SharePoint Online. When disabled, the label handling options on the Sensitive Data page are hidden and no labels are applied to or read from files during scans. | + +:::note +Disabling MIP Labeling does not remove existing labels from files. It stops Access Analyzer from applying or updating labels in future scans. +::: + +## File Scanning + +These settings control which files are included in content classification during sensitive data scans. Adjusting them can reduce scan duration in environments with large binary or media files. + +:::note +File metadata — name, size, permissions, and owner — is always collected regardless of file size or extension settings. These limits apply only to content classification during sensitive data scans. +::: + +### SMB / CIFS + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| **Maximum file size** | 10 MB | 1–100 MB | Files larger than this limit are skipped during content classification. | +| **Excluded extensions** | `.exe, .msi, .bat, .png, .jpg, .jpeg, ...` | — | Comma-separated list of file extensions to skip. Add extensions to reduce scan time on known binary or media content. | + +### SharePoint Online + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| **Maximum file size** | 1 MB | 1–50 MB | Files larger than this limit are skipped during content classification. | +| **Excluded extensions** | `.exe, .msi, .bat, .png, .jpg, .jpeg, ...` | — | Comma-separated list of file extensions to skip. | + +## Scanning — Execution History Retention + +Access Analyzer automatically purges old execution records on a nightly schedule based on these thresholds. + +| Setting | Default | Range | Description | +| --- | --- | --- | --- | +| **Scan execution retention** | 90 days | 7–365 days | How long scan execution records are retained before automatic deletion. | +| **Sync execution retention** | 90 days | 7–365 days | How long identity sync execution records are retained before automatic deletion. | + +:::note +Reducing retention frees database storage. Increasing it extends the history available in **Configuration** > **Source Groups** > **Scan Executions**. +::: + +## Activity Monitor + +The Activity Monitor category contains settings for the built-in TCP listener and the enrollment token used when connecting Netwrix Activity Monitor (NAM) agents to Access Analyzer. + +### Enrollment Token + +The enrollment token is a short-lived credential that NAM agents present during their first connection to Access Analyzer. You generate it here and paste it into the NAM agent output configuration. + +1. Scroll to the **Activity Monitor** section and locate **Enrollment Token**. +2. Click **Generate Token**. +3. Copy the token using the clipboard icon. +4. Paste the token into your NAM agent output configuration before it expires. + +:::note +Tokens expire after **1 hour**. Generating a new token immediately invalidates any previously issued token. A single token can enroll multiple agents simultaneously — generate it immediately before starting your enrollment session. +::: + +For the full step-by-step setup walkthrough, see [Activity Monitor Integration](activity-monitor-integration.md). + +### Listener settings + +The remaining settings in the Activity Monitor category control TCP listener behavior — connection limits, batch sizes, buffer sizes, and timeouts. The defaults are appropriate for most deployments. For a description of each setting and guidance on tuning, see the [Activity Monitor Integration — Application Settings Reference](activity-monitor-integration.md#application-settings-reference) section. + +## Branding + +| Setting | Default | Description | +| --- | --- | --- | +| **Company name** | Netwrix | Displayed in the application interface. | +| **Support email** | support@netwrix.com | Email address shown to users when they need assistance. Update this to your internal helpdesk address after initial setup. | + +## Resetting and cache behavior + +**Resetting to default:** Each setting has a reset action that restores the factory default value. Resetting one setting does not affect any other settings. + +**Cache:** Application Settings are cached for up to 5 minutes. Changes take effect immediately on the instance that applied them. Other running instances pick up the change within 5 minutes. To force an immediate refresh across all instances, click **Refresh Cache** at the top of the page. diff --git a/docs/accessanalyzer/2601/configurations/identity-provider.md b/docs/accessanalyzer/2601/configurations/identity-provider.md new file mode 100644 index 0000000000..c9fe75b467 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/identity-provider.md @@ -0,0 +1,190 @@ +--- +title: "Identity Provider" +description: "Configure single sign-on with an external Identity Provider in Access Analyzer" +sidebar_position: 75 +--- + +# Identity Provider + +Access Analyzer supports federation with your organization's identity system so that users can sign in with their existing corporate credentials. Authentication is handled by your identity provider; roles and permissions are managed within Access Analyzer. + +Setting up an identity provider connection is a two-part process: first you configure the integration in your identity system, then you prepare user accounts inside Access Analyzer. + +:::note +Before completing the steps below, confirm that the infrastructure and network requirements for your IdP type are in place. See [Configure Identity Provider](../install/identity-provider.md) in the Installation section. +::: + +## Supported integration types + +| Type | Description | +| --- | --- | +| **LDAP / Active Directory** | Access Analyzer connects directly to your LDAP directory or Active Directory. Users enter their directory credentials on the Access Analyzer login page — no redirect occurs. | + +## Part 1: Configure your identity provider + +:::tip +For a complete Active Directory walkthrough that pairs this user-configuration guide with the installer-side steps, see the [Quick Install](../install/quickinstall.md). +::: + + + +### LDAP / Active Directory + +No application registration or callback URL is required for LDAP. Prepare the following before connecting. + +**Service account:** + +Create a dedicated, read-only service account in your directory with read access to the user base DN. For Active Directory, the account needs **Read** permission on the user OU. No write access or special group membership is required. + +**Network access:** + +The Access Analyzer cluster must be able to reach your LDAP server on the configured port (389 for LDAP, 636 for LDAPS). Confirm that this traffic is permitted from the Access Analyzer cluster's egress IP range. + +:::warning +Plain LDAP (`ldap://`) transmits credentials in cleartext. Use `ldaps://` (port 636) for production deployments. +::: + +Collect the following values: + +| Value | Description | +| --- | --- | +| **LDAP server URL** | Including protocol and port — for example, `ldaps://corp.example.com:636` | +| **Service account DN** | The distinguished name of the read-only service account | +| **Service account password** | — | +| **Users base DN** | The path where user accounts are stored — for example, `ou=users,dc=example,dc=com` | +| **Email attribute name** | The LDAP attribute that holds the user's email address (usually `mail`) | +| **Directory type** | Active Directory or generic LDAP | + +## Part 2: Prepare Access Analyzer + +### Sign in as the bootstrap User Admin + + + + +The installer seeds a bootstrap account, `admin@dspm.local`, with the **User Admin** role. This account can create and manage other users but **cannot** access system configuration. Use it on first login to pre-provision your users, then sign out and sign back in as an Administrator for system-level work. + +1. Retrieve the bootstrap admin password from the Kubernetes secret: + + ```bash + sudo kubectl get secret -n access-analyzer dspm-bootstrap-admin \ + -o jsonpath='{.data.password}' | base64 -d; echo + ``` + +2. Open a browser and navigate to `https://`. + +3. Sign in with: + - **Username**: `admin@dspm.local` + - **Password**: (from step 1) + +4. Complete first-login setup: + - Scan the QR code with an authenticator app, enter a device name, submit the one-time code. **Save this enrollment** — you will need the same authenticator for any future bootstrap admin login. + - Enter a first name and last name. **Do not change the email address.** + +Proceed to [Pre-provision user accounts](#pre-provision-user-accounts) below. + + + +### Pre-provision user accounts + +Before a user can sign in through the identity provider, their account must exist in Access Analyzer. The application authenticates them against your IdP successfully but denies access if no matching account has been created. + +:::note +The email address entered during pre-provisioning must exactly match the address sent by the IdP or stored in the LDAP `mail` attribute, including case. A mismatch causes sign-in to fail. +::: + +1. Navigate to **Configuration** > **Users**. +2. Click **Add User**. +3. Enter the user's **Name** and **Email** address. +4. Select a **Role**: **Administrator**, **User Admin**, or **Viewer** (see [Roles](#roles) below). +5. Click **Create User**. + +Assign at least one user the **Administrator** role — the bootstrap `admin@dspm.local` account is a User Admin only and cannot access system configuration. Assign at least one additional user the **User Admin** role if you want a non-bootstrap user to manage accounts going forward. + +No password is required for pre-provisioned accounts. For details on managing users, see [Users](users.md). + +### Roles + + + + +Access Analyzer has three roles. The bootstrap `admin@dspm.local` account is seeded as User Admin, so it can pre-provision the rest of your users, including your first Administrator. + +| Role | Description | +| --- | --- | +| **Administrator** | Full access: system configuration (sources, scans, connectors, application settings) and user management (create, edit, activate, deactivate, and delete users; assign roles; pre-provision federated users). | +| **User Admin** | User and role management rights only: create, edit, activate, deactivate, and delete users; assign roles; pre-provision federated users. Does **not** have system configuration rights. The bootstrap `admin@dspm.local` account is assigned this role. | +| **Viewer** | Read-only access to data and reports. No configuration or user management rights. | + + + +## How sign-in works after IdP is configured + +When identity provider integration is active, the Access Analyzer login page presents a credential form that validates against your directory. + +On first sign-in, Access Analyzer matches the email address from the IdP token or LDAP directory to the pre-provisioned account and permanently links the IdP identity to that account. On all subsequent sign-ins, the user's unique IdP identifier is used directly. + +Sessions are valid for up to 8 hours from sign-in and expire after 4 hours of inactivity. + +## Constraints + +| Item | Detail | +| --- | --- | +| **Pre-provisioning required** | Users must have an account in Access Analyzer before their first sign-in. | +| **Email must match exactly** | The email entered during pre-provisioning must match what the IdP or LDAP directory sends, including case. | +| **Roles managed in Access Analyzer** | Roles and permissions are set in Access Analyzer, not in your IdP or directory. | +| **Local accounts coexist** | The administrator account created at deployment remains a local account and continues to sign in with a password. | +| **Password reset unavailable for federated accounts** | The **Reset Password** action in the Users page is available for local accounts only. Federated users manage their credentials through your IdP. | +| **Name and email locked after first sign-in** | Once a user has signed in at least once, their name and email are set from the IdP token and can't be changed in the Access Analyzer UI. Update them in your IdP instead. | diff --git a/docs/accessanalyzer/2601/configurations/logs.md b/docs/accessanalyzer/2601/configurations/logs.md new file mode 100644 index 0000000000..fe3890fab4 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/logs.md @@ -0,0 +1,108 @@ +--- +title: "System Logs" +description: "Viewing, filtering, and downloading system logs in Access Analyzer" +sidebar_position: 90 +--- + +# System Logs + +The System Logs page displays application-wide log entries generated by Access Analyzer services. Use it to monitor activity, investigate scan failures, and collect diagnostic information for support. + +Navigate to **Configuration** > **System Logs** to open the page. + +## Log entry fields + +Each log entry contains the following fields. + +| Field | Description | +| --- | --- | +| **Timestamp** | The date and time the log entry was generated. | +| **Level** | The severity of the entry: **Error**, **Warn**, **Info**, or **Debug**. | +| **Component** | The internal service that generated the entry (for example, `core-api`, `connector-api`, or `scanner`). Displays **—** if not available. | +| **Source** | The data source associated with the entry, if any. Displays **—** for entries not tied to a specific source. | +| **Message** | The log message text. Hover over a truncated message to see the full text. | + +## Filter logs + +The toolbar above the log table provides five independent filters. All active filters are applied together — only entries matching all conditions are shown. Filter state is preserved in the page URL, so you can bookmark or share a filtered view. + +**Search** + +Type in the search field to filter by message text. Results update after a short pause while you type. + +**Level** + +Select a severity level to show only entries at that level. The default shows all levels. + +| Level | Description | +| --- | --- | +| **Error** | Failures that require attention. | +| **Warn** | Conditions that may indicate a problem. | +| **Info** | General operational events. | +| **Debug** | Detailed diagnostic output. | + +**Component** + +Select one or more components to show entries from those services only. The component list is populated from services that have generated logs. + +**Source** + +Select a data source to show only log entries associated with it. The source list includes sources that have activity in the past seven days. + +**Date range** + +Use the **From** and **To** fields to restrict entries to a specific time window. Both fields are optional — set only one to filter from or until a given time. + +## Sort and paginate + +The log table is sorted by timestamp, newest first by default. Click the **Timestamp** column header to reverse the sort order. + +Use the rows-per-page control to display 10, 25, 50, or 100 entries per page. + +## Download logs + +To export log entries for offline review or to provide to support: + +1. Apply any filters you want to include in the export. +2. Click the **Download** button in the toolbar. +3. Select **JSON** or **CSV** from the dropdown. + +The export file is named `system-logs-{timestamp}` and reflects all currently active filters. Exports are limited to 10,000 entries. + +CSV exports include the following columns: Timestamp, Level, Message, Trace ID, Span ID, and Attributes. + +## Common troubleshooting scenarios + +### Investigate a scan failure + +When a scan does not complete as expected: + +1. Set the **Source** filter to the data source the scan was running against. +2. Set the **Level** filter to **Error**. +3. Set the **Date range** to the window when the scan ran. +4. Review the **Message** column for error details. + +If no error-level entries appear, clear the **Level** filter and check for **Warn** entries that may indicate a configuration or connectivity issue. + +### Review logs for a specific time window + +1. Enter the start time in the **From** field. +2. Enter the end time in the **To** field. +3. Leave other filters clear to see all activity in that window. + +Use this approach to identify what was happening in the system around the time of an observed issue. + +### Isolate logs from a specific service + +1. Open the **Component** dropdown. +2. Select the service you want to focus on. + +Multiple components can be selected at the same time to compare activity across services. + +### Collect logs for a support case + +1. Set the **Date range** to cover the period when the issue occurred. +2. If the issue is tied to a specific data source, set the **Source** filter. +3. Click **Download** and select **JSON** to preserve full attribute metadata. + +Provide the downloaded file along with your support request. diff --git a/docs/accessanalyzer/2601/configurations/sensitive-data.md b/docs/accessanalyzer/2601/configurations/sensitive-data.md new file mode 100644 index 0000000000..3cced196f6 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/sensitive-data.md @@ -0,0 +1,154 @@ +--- +title: "Sensitive Data" +description: "Configure sensitive data scanning settings in Access Analyzer" +sidebar_position: 30 +--- + +# Sensitive Data + +The Sensitive Data configuration page defines which types of sensitive content Access Analyzer identifies during scans, whether to run optical character recognition (OCR) on images, and how Microsoft Information Protection (MIP) sensitivity labels are applied to matching files. These settings apply globally and serve as the default for all sensitive data scans. + +Navigate to **Configuration** > **Sensitive Data** to view and update the configuration. + +The page has two sections: + +- **Microsoft Information Protection (MIP) Configuration** — connects an Entra ID tenant so Access Analyzer can retrieve your organization's MIP sensitivity labels. +- **Sensitive Data Types** — controls which data types are active for scanning and optionally maps each type to a MIP label. + +## MIP configuration + +The MIP configuration section connects Access Analyzer to a Microsoft Entra ID tenant. When a tenant is connected, Access Analyzer retrieves the sensitivity labels defined in your organization's MIP policy and makes them available for mapping in the Sensitive Data Types table. + +### Select a tenant + +1. In the **Tenant ID** dropdown, select the Entra ID source that represents the tenant whose MIP labels you want to use. +2. Click **Save Configuration**. + +The dropdown lists Entra ID source groups that have completed at least one **Users, Groups and Roles** scan. If the dropdown is empty, either no Entra ID source group exists or the scan has not run yet. Run the scan first, then return to this page to select the tenant. + +After you select a tenant, Access Analyzer retrieves the associated MIP labels. The status bar below the dropdown shows: + +| Indicator | Meaning | +| --- | --- | +| Labels loaded count | The number of MIP labels retrieved from the selected tenant. | +| Invalid mappings count | The number of data types whose previously saved label no longer exists in MIP. | +| Last synced time | How long ago the labels were last synchronized from Entra ID. | + +MIP labels sync automatically from Entra ID at regular intervals. If a label is removed from MIP after you save a mapping, the **MIP Label** column shows the old label name with a warning indicator, and the **Status** column shows **Label Missing**. Update or clear those mappings before saving. + +:::note +The label selector and status badges in the Sensitive Data Types table are disabled until you select a tenant and labels finish loading. +::: + +## Sensitive data types + +The Sensitive Data Types table lists all data types that Access Analyzer can detect. Enable a data type to include it in sensitive data scans. If MIP labels are available, you can also map each data type to a specific label so Access Analyzer applies that label to files that match the data type. + +### Data types + +| Data Type | Description | Includes | +| --- | --- | --- | +| **CCPA** | California Consumer Privacy Act | Social Security numbers, driver's licenses, payment card data, email addresses, IP addresses, personal identifiers for California and Canadian residents | +| **CMMC** | Cybersecurity Maturity Model Certification | Controlled Unclassified Information (CUI) markings, DoD distribution statements (B–F), export control warning labels | +| **Credentials** | Passwords, API keys, and authentication secrets | Private keys (RSA, DSA, EC), passwords, AWS, Azure, and Google Cloud connection strings, PGP key blocks, Kerberos tickets, Slack tokens, SSH authorized keys | +| **Financial Records** | Banking and financial account data | ABA routing numbers, IBAN, SWIFT codes, US bank account numbers | +| **GDPR** | General Data Protection Regulation | National IDs, passports, driver's licenses, and personal identifiers for EU and EEA member states (30 countries including Austria, France, Germany, Italy, Spain, and others) | +| **GDPR Restricted** | Special categories of personal data under GDPR | Health data, political opinions, racial or ethnic origin, religious beliefs, sexual orientation, trade union membership | +| **GLBA** | Gramm-Leach-Bliley Act | Payment card numbers, cardholder names, expiration dates, security codes (Visa, Mastercard, AMEX, Discover, and others), ABA routing numbers, Social Security numbers | +| **HIPAA** | Health Insurance Portability and Accountability Act | ICD-10 diagnosis codes, prescription drug names, medical record numbers, national drug codes, Medicare numbers, Social Security numbers, patient identifiers | +| **PCI DSS** | Payment Card Industry Data Security Standard | Payment card numbers, cardholder names, expiration dates, security codes (Visa, Mastercard, AMEX, Diners Club, Discover, JCB, UnionPay) | +| **PHI** | Protected Health Information | ICD-10 codes, prescription drug names, medical record numbers, country-specific healthcare IDs for 20+ countries including UK NHS numbers, Australian Medicare numbers, and EU health insurance identifiers | +| **PII** | Personally Identifiable Information | Social Security numbers, passports, driver's licenses, full names, dates of birth, home addresses, and national identity documents for 60+ countries | + +### Table columns + +| Column | Description | +| --- | --- | +| Checkbox | Enables or disables the data type for scanning. Select the header checkbox to enable or disable all types at once. | +| **Data Type** | The name of the sensitive data type. | +| **Description** | A short description of what the data type covers. | +| **MIP Label** | The MIP sensitivity label to apply when the data type is detected. Select a label from the dropdown, or select **— No Label —** to detect the data type without applying a label. Available only when a tenant is connected and labels are loaded. | +| **Status** | Reflects the current mapping state for the row. | + +### Status values + +| Status | Color | Meaning | +| --- | --- | --- | +| **No MIP Label** | Gray | No tenant is connected, or labels haven't loaded. No label can be assigned. | +| **Unmapped** | Yellow | A tenant is connected and labels are loaded, but no label is assigned to this data type. | +| **Mapped** | Green | A label is assigned and present in the connected tenant. | +| **Label Missing** | Red | A label was previously assigned but no longer exists in MIP. Update or clear the mapping. | + +### Enable data types + +1. In the Sensitive Data Types table, select the checkbox next to each data type you want to activate. + - To activate all data types at once, select the checkbox in the table header. + - To deactivate all data types at once, clear the header checkbox when all types are selected. +2. Click **Save Configuration**. + +### Assign MIP labels + +You can assign a MIP label to each enabled data type. When Access Analyzer finds a file that matches a data type, it applies the mapped label to that file according to the label handling behavior settings. + +1. Connect a tenant in the MIP Configuration section and wait for labels to load. +2. In the **MIP Label** column for a data type, select a label from the dropdown. + - Labels are grouped into **Default Labels** (Personal, Public, General, Confidential) and **Custom Labels** (labels specific to your organization). + - Select **— No Label —** to detect the data type without applying a label. +3. Repeat for each data type you want to map. +4. Click **Save Configuration**. + +:::note +Enabling a data type and assigning a label are independent. A data type with no label assigned is still detected during scans — Access Analyzer identifies matching files but doesn't apply a MIP label to them. +::: + +## OCR + +The **Run OCR to improve classification of images** option enables optical character recognition during scans. When enabled, Access Analyzer extracts text from images, screenshots, and scanned documents and applies the same classification rules to that text. + +Enabling OCR increases scan processing time. + +1. Select or clear the **Run OCR to improve classification of images** checkbox. +2. Click **Save Configuration**. + +## Label handling behavior + +The **Label Settings** drawer controls whether Access Analyzer writes MIP sensitivity labels back to files during sensitive data scans, and how it handles files that already carry a label. To open it, click **Label Settings** in the upper-right corner of the Sensitive Data Types card. + +These settings apply globally and can be overridden per-scan in the scan configuration. + +:::note +Label write-back applies to **File Server and SharePoint Online sensitive data scans only**. Entra ID and Active Directory scans do not support label application. +::: + +:::note +Label write-back only occurs when **both** conditions are met: a MIP label is mapped to the detected data type in the Sensitive Data Types table, **and** the relevant option below is enabled. All options are off by default — by default, Access Analyzer detects and classifies files but does not write any labels to files. +::: + +### Options + +**Clear label if no longer sensitive** +When enabled, Access Analyzer removes the MIP label from a file if a subsequent scan finds the file no longer matches any enabled sensitive data type. Off by default. + +**Allow overwriting existing labels** +When enabled, Access Analyzer applies the mapped label to files that already have a MIP label assigned. When disabled, files that already carry any MIP label are skipped — only unlabeled files receive a label. Off by default. + +- **Allow downgrading labels** *(requires Allow overwriting existing labels to be on)* + When enabled, Access Analyzer can replace a higher-priority label with a lower-priority one (for example, replacing "Confidential" with "General"). When disabled, only upgrades or equal-priority replacements are applied. This option is unavailable when **Allow overwriting existing labels** is off. Off by default. + +To configure label handling: + +1. Click **Label Settings**. +2. Select or clear the options as needed. +3. Click **Done** to close the drawer. +4. Click **Save Configuration** to apply all pending changes. + +## Save and cancel + +The **Save Configuration** and **Cancel** buttons are inactive until you make a change. + +- **Save Configuration** — saves all pending changes, including data type selections, MIP label mappings, the OCR setting, and label handling behavior. +- **Cancel** — discards all pending changes and restores the form to the last saved state. + +:::note +If you navigate away from the page with unsaved changes, Access Analyzer displays a confirmation dialog before leaving. +::: diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/_category_.json b/docs/accessanalyzer/2601/configurations/service-accounts/_category_.json new file mode 100644 index 0000000000..25ffc0442b --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Service Accounts", + "position": 10, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/client-id-certificate.md b/docs/accessanalyzer/2601/configurations/service-accounts/client-id-certificate.md new file mode 100644 index 0000000000..cbc7eded42 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/client-id-certificate.md @@ -0,0 +1,40 @@ +--- +title: "Client ID/Certificate" +description: "Client ID and certificate credentials for SharePoint Online source groups" +sidebar_position: 4 +--- + +# Client ID/Certificate + +The Client ID/Certificate credential type authenticates with SharePoint Online using certificate-based authentication. Use this credential type when configuring SharePoint Online source groups. + +This requires a registered application in your Entra ID tenant. The certificate itself is generated by the source group wizard — you don't create or upload it here. + +## Create a Client ID/Certificate service account + +1. Navigate to **Configuration** > **Service Accounts**. +2. Click **Add Service Account**. +3. In the **Name** field, enter a descriptive name for this service account. +4. From the **Service account type** drop-down, select **Client ID/Certificate**. + + ![Add service account form showing Client ID/Certificate fields: name, client application ID, and tenant ID](/images/accessanalyzer/2601/configurations/add-service-account-certificate.png) + +5. In the **Client Application ID** field, enter the Application (client) ID from your Entra ID app registration. +6. In the **Tenant ID** field, enter the Directory (tenant) ID of your Entra ID tenant. +7. Click **Add account**. + +## Fields + +| Field | Description | +| --- | --- | +| **Name** | A display name that identifies this service account in Access Analyzer. | +| **Client Application ID** | The Application (client) ID of your registered Entra ID application. Find this in the Azure portal under **Azure Active Directory** > **App registrations** > your app > **Overview**. | +| **Tenant ID** | The Directory (tenant) ID of your Entra ID tenant. Find this in the Azure portal under **Azure Active Directory** > **Overview**. | + +## Certificate + +The certificate is not entered in the service account form. When you set up a SharePoint Online source group, the wizard includes a **Generate and Download Certificate** step that creates the certificate and downloads it to your machine. You then upload the certificate to your registered Entra ID application in the Azure portal before testing the connection. + +If you update the service account on an existing source group, the new account's certificate must be uploaded to the registered app before saving. + +For steps to register the application and upload the certificate, see [SharePoint Online Connector Requirements](../../connectors/sharepoint-online/overview.md). diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/client-id-secret.md b/docs/accessanalyzer/2601/configurations/service-accounts/client-id-secret.md new file mode 100644 index 0000000000..ed14b2d54a --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/client-id-secret.md @@ -0,0 +1,34 @@ +--- +title: "Client ID/Secret" +description: "Client ID and secret credentials for Entra ID source groups" +sidebar_position: 3 +--- + +# Client ID/Secret + +The Client ID/Secret credential type authenticates with Microsoft Entra ID via the Microsoft Graph API. Use this credential type when configuring Entra ID source groups. + +This requires a registered application in your Entra ID tenant with the appropriate API permissions granted. + +## Create a Client ID/Secret service account + +1. Navigate to **Configuration** > **Service Accounts**. +2. Click **Add Service Account**. +3. In the **Name** field, enter a descriptive name for this service account. +4. From the **Service account type** drop-down, select **Client ID/Secret**. + + ![Add service account form showing Client ID/Secret fields: name, client application ID, and client secret](/images/accessanalyzer/2601/configurations/add-service-account-client-secret.png) + +5. In the **Client Application ID** field, enter the Application (client) ID from your Entra ID app registration. +6. In the **Client Secret** field, enter a client secret value generated for the registered application. +7. Click **Add account**. + +## Fields + +| Field | Description | +| --- | --- | +| **Name** | A display name that identifies this service account in Access Analyzer. | +| **Client Application ID** | The Application (client) ID of your registered Entra ID application. Find this in the Azure portal under **Azure Active Directory** > **App registrations** > your app > **Overview**. | +| **Client Secret** | A client secret generated for the registered application. Create one in the Azure portal under your app's **Certificates & secrets**. | + +For steps to register the application and grant the required API permissions, see [Entra ID Requirements](../../connectors/entra-id/overview.md). diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/overview.md b/docs/accessanalyzer/2601/configurations/service-accounts/overview.md new file mode 100644 index 0000000000..ac39ff44b0 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/overview.md @@ -0,0 +1,36 @@ +--- +title: "Overview" +description: "How service accounts work in Access Analyzer and which credential type each data source requires" +sidebar_position: 1 +--- + +# Overview + +Service accounts store the credentials Access Analyzer uses to authenticate against data sources during scans. Each data source connector requires a specific credential type, and the source group wizard automatically selects the correct type when you set up a new source group. + +Navigate to **Configuration** > **Service Accounts** to manage service accounts. + +![Service Accounts list showing existing accounts by name, type, source group, and creation date](/images/accessanalyzer/2601/configurations/service-accounts-list.png) + +## Credential types by data source + +| Data Source | Credential Type | +| --- | --- | +| Active Directory | [Username and Password](./username-password.md) | +| File Server | [Username and Password](./username-password.md) | +| Entra ID | [Client ID/Secret](./client-id-secret.md) | +| SharePoint Online | [Client ID/Certificate](./client-id-certificate.md) | +| SSH-based sources | [SSH Username/Key](./ssh-username-key.md) | + +## Creating a service account + +You can create a service account in two ways: + +- **In advance from Configuration** — Navigate to **Configuration** > **Service Accounts** and click **Add Service Account**. Select the credential type and enter the required fields. +- **Inline during source group setup** — Click **+** next to the **Service Account** field in the source group wizard. The wizard locks the credential type to match the connector being configured. + +## Editing service accounts + +Credential fields — passwords and client secrets — are never pre-populated when you edit an existing service account. You must re-enter them each time you save changes. + +Updating the service account on an existing source group replaces the credentials used for all future scans in that source group. Ensure the replacement account has the required permissions before saving. diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/ssh-username-key.md b/docs/accessanalyzer/2601/configurations/service-accounts/ssh-username-key.md new file mode 100644 index 0000000000..52824412a0 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/ssh-username-key.md @@ -0,0 +1,30 @@ +--- +title: "SSH Username/Key" +description: "SSH username and private key credentials for source groups that require SSH-based authentication" +sidebar_position: 5 +--- + +# SSH Username/Key + +The SSH Username/Key credential type authenticates using an SSH username and private key. Use this credential type for source groups that connect to hosts over SSH. + +## Create an SSH Username/Key service account + +1. Navigate to **Configuration** > **Service Accounts**. +2. Click **Add Service Account**. +3. In the **Name** field, enter a descriptive name for this service account. +4. From the **Service account type** drop-down, select **SSH Username/Key**. + + ![Add service account form showing SSH Username/Key fields: name, SSH username, and SSH key](/images/accessanalyzer/2601/configurations/add-service-account-ssh.png) + +5. In the **SSH Username** field, enter the username for the SSH account. +6. In the **SSH Key** field, paste the SSH private key. +7. Click **Add account**. + +## Fields + +| Field | Description | +| --- | --- | +| **Name** | A display name that identifies this service account in Access Analyzer. | +| **SSH Username** | The username of the SSH account on the target host. | +| **SSH Key** | The SSH private key used to authenticate. Paste the full private key including the header and footer lines. | diff --git a/docs/accessanalyzer/2601/configurations/service-accounts/username-password.md b/docs/accessanalyzer/2601/configurations/service-accounts/username-password.md new file mode 100644 index 0000000000..669b47733c --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/service-accounts/username-password.md @@ -0,0 +1,42 @@ +--- +title: "Username and Password" +description: "Username and password service accounts for Active Directory and file server source groups" +sidebar_position: 2 +--- + +# Username and Password + +The Username and Password credential type is used by Active Directory and file server source groups. Both require a domain account whose credentials Access Analyzer uses to connect and authenticate during scans. + +## Create a Username/Password service account + +1. Navigate to **Configuration** > **Service Accounts**. +2. Click **Add Service Account**. +3. In the **Name** field, enter a descriptive name for this service account. +4. From the **Service account type** drop-down, select **Username/Password**. + + ![Add service account form showing Username/Password fields: name, username, and password](/images/accessanalyzer/2601/configurations/add-service-account-username-password.png) + +5. In the **Username** field, enter the domain account in `DOMAIN\username` or `username@domain` format. +6. In the **Password** field, enter the account password. +7. Click **Add account**. + +## Fields + +| Field | Description | +| --- | --- | +| **Name** | A display name that identifies this service account in Access Analyzer. | +| **Username** | The domain user account in `DOMAIN\username` or `username@domain` format. | +| **Password** | The password for the domain account. | + +## Active Directory + +Active Directory source groups use the service account to connect to domain controllers over LDAP or LDAPS and read directory objects. The account must have Read access to the Active Directory directory tree. + +For full permission requirements, see [Active Directory Connector Requirements](../../connectors/activedirectory.md). + +## File Server + +File server source groups use the service account to connect to Windows file servers over SMB and enumerate shares, permissions, and file contents. The account must be a member of the same domain as the target file servers. The specific permissions required depend on the scan types you enable — access scanning and sensitive data scanning have different requirements. + +For full permission requirements, see [CIFS / SMB File Share](../../connectors/file-servers/cifs.md). diff --git a/docs/accessanalyzer/2601/configurations/source-groups/_category_.json b/docs/accessanalyzer/2601/configurations/source-groups/_category_.json new file mode 100644 index 0000000000..e3bbafe95d --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Source Groups", + "position": 20, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scan-executions.md b/docs/accessanalyzer/2601/configurations/source-groups/scan-executions.md new file mode 100644 index 0000000000..25364459e3 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scan-executions.md @@ -0,0 +1,49 @@ +--- +title: "Scan Executions" +description: "Understanding scan execution status and history in Access Analyzer" +sidebar_position: 3 +--- + +# Scan Executions + +A scan execution is a single run of a scan at a specific point in time. Each time Access Analyzer runs a scan — whether triggered by a schedule or manually — it creates a new scan execution record. Execution history is retained per source so you can review past run outcomes. + +Scan executions are distinct from scan configurations. The [scan configuration](scans.md) defines what to collect and when. The scan execution records what happened during a specific run. + +## Execution status values + +| Status | Meaning | +| --- | --- | +| **Pending** | The execution is queued and waiting to start. This occurs when the Max Concurrent Scans limit is reached and additional executions are waiting their turn. | +| **Running** | The scanner is actively collecting data from the source. | +| **Pausing** | A pause was requested. The execution is finishing its current operation before pausing. | +| **Paused** | The execution has paused mid-run and can be resumed. | +| **Resuming** | A resume was requested. The execution is restarting from where it paused. | +| **Stopping** | A stop was requested. The execution is finishing its current operation before terminating. | +| **Post-processing** | Data collection is complete. Results are being processed and written to the database. | +| **Completed** | The execution finished successfully. | +| **Stopped** | The execution was manually stopped before completing. Partial results may have been collected. | +| **Cancelled** | The execution was cancelled before it started or early in the run. No results were collected. | +| **Failed** | The execution encountered an error and did not complete. Check the execution log for details. | + +## Source group scan status + +The source groups list displays an aggregate scan status for each group. This is computed from the most recent scan execution across all sources in the group, using the following priority order: + +1. **Paused** — One or more sources has a paused execution, and none are running. +2. **Running** — One or more sources has an execution in a pending, running, pausing, resuming, stopping, or post-processing state. +3. **Failed** — One or more sources has a failed execution, and none are running or paused. +4. **Completed** — All sources have completed their most recent execution successfully. +5. **Completed with errors** — One or more sources has a stopped or cancelled execution, and none meet the criteria above. +6. **Not run yet** — No scan executions exist for any source in the group. + +This means a group shows **Running** even if only one source is actively scanning, and it shows **Failed** only when no scans are still in progress. + +## Blocked operations during active executions + +Several operations are blocked while a source has an execution in an active state (pending, running, pausing, paused, resuming, stopping, or post-processing): + +- **Deleting a source group** — Stop all active scans before deleting the group. +- **Removing a source from a group** — Stop the source's active scan before removing it. + +Wait for the execution to reach a terminal state (completed, stopped, cancelled, or failed), or use the **Stop** action to terminate it, before proceeding with the blocked operation. diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/_category_.json b/docs/accessanalyzer/2601/configurations/source-groups/scanners/_category_.json new file mode 100644 index 0000000000..1f2304bcca --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Scanners", + "position": 40, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/best-practices.md b/docs/accessanalyzer/2601/configurations/source-groups/scanners/best-practices.md new file mode 100644 index 0000000000..deee012cd1 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/best-practices.md @@ -0,0 +1,100 @@ +--- +title: "Scanner Best Practices" +description: "Best practices for configuring and running scanners in Access Analyzer" +sidebar_position: 50 +--- + +# Scanner Best Practices + +## Use scanner labels to isolate scan traffic + +Scanner labels route scan executions to specific scanner pools. Use them to keep scan traffic between environments isolated and prevent resource contention. + +Common labeling patterns: + +| Use case | Example label | +|----------|---------------| +| Separate production and non-production scanning | `environment=production`, `environment=staging` | +| Route by geographic region | `region=us-east`, `region=eu-west` | +| Dedicate scanners to high-sensitivity source groups | `tier=restricted` | + +Define a labeling scheme before deploying scanners and apply it consistently. Labels assigned to a source group are used by all scan executions in that group — you don't need to set them per source. + +### Label matching behavior + +When a source group has multiple labels configured, a scan is routed to any scanner that matches **at least one** of those label pairs — not all of them. Design your label scheme with this in mind: a scanner carrying `region=us-east` will receive jobs from a source group labeled `region=us-east, tier=restricted` even if the scanner does not carry the `tier=restricted` label. + +For strict isolation, use a single label per source group or ensure scanners are labeled precisely to match only the intended groups. + +### Label key and value constraints + +Label keys and values entered in the Deploy Scanner wizard must follow these rules: + +| Field | Allowed characters | Max length | +|-------|-------------------|------------| +| Key | Letters, digits, hyphens | 53 characters | +| Value | Letters, digits, hyphens, underscores, dots | 63 characters | + +Both key and value must start with a letter or digit. Labels are stored with a `dspm.netwrix.com/scanner-` prefix internally — you do not need to include this prefix when entering labels in the wizard. + +:::note +The label `scanner-default` is reserved for the built-in system scanner and can't be applied to custom scanners. +::: + +## Plan for scanner redundancy + +Assign the same label to multiple scanners that cover the same environment. Scanners sharing a label form a pool — when a scan job is dispatched, Access Analyzer routes it to any available scanner in the pool. If one scanner is offline, unhealthy, or busy, the job routes to another scanner carrying the same label automatically. + +A single scanner per label is a single point of failure. For production environments, deploy at least two scanners per label. This also distributes scan load across the pool when multiple source groups target the same label simultaneously. + +## Set Workers conservatively + +The **Workers** setting controls the number of concurrent enumeration threads a scan uses when reading from a target. The default is `3` and the valid range is `1–20`. + +Start at the default and increase only after validating that the target environment can handle parallel connections. + +Before increasing Workers: + +- Confirm the domain controller, file server, or other target can sustain simultaneous authenticated connections without degraded performance. +- Verify the network path between the scanner and the target has sufficient bandwidth for parallel data transfer. +- Consider the number of source groups that may run at the same time — multiple groups can run simultaneously across the same scanner, multiplying the actual connection count on the target. + +A safe approach is to increase by 2–3 at a time and monitor scan completion times and target resource utilization before increasing further. + +## Monitor scanner health + +Check the Scanners page regularly to review scanner health status. A scanner in Warning state is under resource pressure — disk, memory, or CPU — and scan performance may be degraded. A scanner in Error state has reported health issues and needs investigation before running additional scans. + +Common causes of Warning and Error states: + +- Disk space consumed by k3s container images or log files — clean up unused images if disk pressure is persistent +- Memory pressure from running multiple large scans in parallel — reduce Workers or stagger scan schedules +- Network connectivity issues between the scanner host and the Access Analyzer server on port 6443 + +See [Manage Scanners](./manage-scanners.md) for a full reference of health status values. + +## Group sources by environment and sensitivity + +Group sources that share the same operational profile — same environment (production vs. staging), same geographic location, and similar sensitivity level. Avoid mixing high-sensitivity and low-priority sources in a single group. + +This lets you assign dedicated scanner pools and service accounts to each group based on security requirements, and keeps aggregate scan status meaningful. + +## Use least-privilege service accounts + +Each source group requires a service account for authentication against the targets it scans. Assign an account that has only the permissions required for the connectors in that group. + +- Don't share a single service account across source groups that scan different environments. +- Don't reuse a service account between source groups with different sensitivity levels. +- Review service account permissions when adding new sources to an existing group — the account must have access to each new source. + +## Follow a consistent naming convention + +Source group names appear in the list view, in scan execution logs, and in reporting. A consistent naming convention makes groups easier to identify and manage. + +A useful pattern: `--`. For example: + +- `ad-production-us-east` +- `fileserver-staging-eu-west` +- `fileserver-production-eu-central` + +Names are case-insensitive and must be unique across all source groups. Avoid names that embed credentials, IP addresses, or other values that change over time. diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/deploy-scanner.md b/docs/accessanalyzer/2601/configurations/source-groups/scanners/deploy-scanner.md new file mode 100644 index 0000000000..f01f6eeac3 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/deploy-scanner.md @@ -0,0 +1,77 @@ +--- +title: "Deploy a Scanner" +description: "Register a custom scanner node in Access Analyzer" +sidebar_position: 30 +--- + +# Deploy a Scanner + +Deploying a scanner registers a remote Linux host as a custom scanner node in Access Analyzer. After deployment, the scanner appears in the Scanners table and becomes available for selection in source group configuration. + +## Before you begin + +- Confirm the scanner host meets all [requirements](./requirements.md). +- Create an **SSH Username / SSH Key** service account in Access Analyzer with access to the scanner host. You can also create it inline during the wizard — see step 7 below. +- Have the scanner host's public SSH host key ready. You can retrieve it by running the following command from any machine that can reach the host, replacing `` with the scanner's hostname or IP address: + + ```bash + ssh-keyscan + ``` + + Copy the line that begins with the host's address followed by the key type (for example, `ecdsa-sha2-nistp256`) and the key value. + +## Deploy the scanner + +1. Navigate to **Configuration** > **Scanners**. +2. Click **Deploy Scanner**. The Deploy Scanner drawer opens. +3. In the **Name** field, enter a display name for the scanner (for example, `Production Scanner`). This name identifies the scanner in the Scanners table and in source group configuration. +4. In the **SSH Host** field, enter the hostname or IP address of the scanner host (for example, `node01.company.com` or `192.168.1.50`). +5. In the **SSH Host Key** field, paste the public SSH host key you retrieved during preparation. Access Analyzer uses this key to verify the host identity during registration. +6. In the **SSH Port** field, enter the SSH port if your scanner host uses a non-standard port. Defaults to `22` if left blank. +7. In the **Service Account** dropdown, select the SSH Username / SSH Key account that has access to the scanner host. + + - To create a new service account without leaving the wizard, click **+** next to the dropdown. The account type is pre-set to SSH Username / SSH Key. After saving, the new account is automatically selected and all other fields are preserved. + - To edit the selected account, click the pencil icon. The SSH key field is blank in edit mode — you must re-enter the private key before saving. + +8. Under **Labels**, add at least one label. You must add at least one label before the scanner can be deployed — the **Deploy** button remains disabled until a label is applied. + + - Enter a key and a value, then click **Add**. The label appears as a chip. + - To add additional labels, repeat the process. + - To remove a label, click the **×** on its chip. + - Label keys and values are automatically normalized to lowercase with spaces converted to hyphens. + + :::tip + Previously used labels appear as chips you can click to pre-fill the key and value fields. This helps you apply consistent labels across multiple scanners. + ::: + +9. Optionally, click **Test connection** to verify that Access Analyzer can reach the scanner host over SSH before deploying. A green indicator confirms connectivity; a red indicator with a message identifies the problem. + +10. Click **Deploy**. Access Analyzer connects to the scanner host over SSH and runs the registration script. + +## What happens during registration + +Registration runs automatically and typically completes within five minutes. During registration, Access Analyzer: + +1. Runs a preflight check on the scanner host to verify all requirements are met (curl, bash, passwordless sudo, disk space, memory, and CPU). +2. Downloads and installs k3s (a lightweight Kubernetes distribution) on the scanner host. +3. Joins the scanner host to the Access Analyzer Kubernetes cluster as a worker node. +4. Applies the labels you specified. + +If registration takes longer than five minutes, check network connectivity and confirm the scanner host can reach `https://get.k3s.io`. Slow networks or resource-constrained hosts may require additional time. + +## After deployment + +The scanner appears immediately in the Scanners table. Its health status shows **Healthy** once the node has fully joined the cluster. + +To use the scanner, assign it to a source group by selecting **Custom scanner** under **Scanner Location** when setting up or editing a source group, and matching its label. See [Set Up File Server Source Group](../../../gettingstarted/file-servers/set-up-source-group.md) or the equivalent guide for your connector. + +## Edit a scanner + +To update a scanner's labels or service account after deployment: + +1. Navigate to **Configuration** > **Scanners**. +2. Click the edit icon on the scanner row. The Deploy Scanner drawer opens with the scanner's current configuration pre-filled. +3. Update the labels or service account as needed. +4. Click **Save Changes**. + +Changes appear immediately in the Scanners table and in the scanner selection dropdown in source group configuration. diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/manage-scanners.md b/docs/accessanalyzer/2601/configurations/source-groups/scanners/manage-scanners.md new file mode 100644 index 0000000000..57e3b4d3ac --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/manage-scanners.md @@ -0,0 +1,66 @@ +--- +title: "Manage Scanners" +description: "View scanner health, edit scanner configuration, and delete scanners in Access Analyzer" +sidebar_position: 40 +--- + +# Manage Scanners + +The Scanners page lists all registered scanner nodes and their current status. Navigate to **Configuration** > **Scanners** to access it. + +## Scanners table + +Each row in the table represents one registered scanner. + +| Column | Description | +|--------|-------------| +| Name / IP | Hostname or IP address of the scanner host | +| Labels | Labels assigned to the scanner, displayed as chips. If a scanner has more than two labels, the first two are shown with an overflow count (for example, **+3**). Hover over the count to see all labels. | +| Source Groups | Number of source groups that target this scanner | +| Sources | Total number of sources assigned to this scanner | +| Scanning | Number of sources being scanned at this time | +| Health Status | Current health of the scanner node | +| Scan Status | Whether the scanner is idle or actively running a scan | +| Version | Scanner software version. If an update is available, an **Update** action appears. | + +## Health status + +| Status | Color | Meaning | +|--------|-------|---------| +| Healthy | Green | The scanner node is reachable and operating normally | +| Warning | Yellow | The node is reachable but under resource pressure (disk, memory, or CPU) | +| Error | Red | The node is reachable but in an unhealthy state | +| Offline | Gray | The node is not reachable from the Access Analyzer server | + +Scans may perform poorly on a scanner in Warning state — consider resolving the resource pressure before scheduling large scans. Investigate the scanner host when the status is Error. An Offline scanner cannot run scans — source groups that target it will not execute until the scanner comes back online or a different scanner with the matching label becomes available. + +## Scan status + +| Status | Color | Meaning | +|--------|-------|---------| +| Idle | Gray | No scans are running on this scanner | +| In Progress | Blue | One or more scans are running | + +## Search scanners + +Use the search field at the top of the page to filter the scanner list. The search matches against scanner names, IP addresses, and label values. Results update as you type. + +## Connect a scanner to source groups + +If a scanner has no associated source groups, a **+ Connect source** action appears on its row. Click it to assign source groups that will use this scanner. + +To route scans from a source group to a specific scanner or scanner pool, set the scanner location when configuring the source group. Match the source group's scanner selection to the label on the scanner you want to use. + +## Delete a scanner + +:::warning +Deleting a scanner removes it from the cluster. Source groups that target the deleted scanner's labels will not be able to run scans unless another scanner with the same labels is available. +::: + +To delete a scanner: + +1. Navigate to **Configuration** > **Scanners**. +2. Click the delete icon on the scanner row. +3. Confirm the deletion. + +A scanner can only be deleted when no scan jobs are running on it. If scans are in progress, wait for them to complete before deleting. The system scanner (built-in scanner on the Access Analyzer server) cannot be deleted. diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/overview.md b/docs/accessanalyzer/2601/configurations/source-groups/scanners/overview.md new file mode 100644 index 0000000000..9b0ec2f071 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/overview.md @@ -0,0 +1,65 @@ +--- +title: "Scanners Overview" +description: "Overview of scanner types, architecture, and how to use them in Access Analyzer" +sidebar_position: 10 +--- + +# Scanners Overview + +Scanners are the execution nodes that run scan workloads in Access Analyzer. Every scan runs on a scanner — either the built-in system scanner or a custom scanner you deploy on a remote host. + +## Scanner types + +Access Analyzer provides two scanner types: + +**System scanner** — The built-in scanner that runs on the Access Analyzer server itself. It's available immediately with no configuration and is the default for all source groups. Use it when the Access Analyzer server can reach your target resources directly over the network. + +**Custom scanners** — Scanners you deploy on separate Linux hosts closer to your data sources. Use custom scanners when: + +- Target file servers or Active Directory domain controllers are in network segments the Access Analyzer server can't reach directly +- You want to reduce scan traffic over wide area network (WAN) links between sites +- You need to distribute scan load across multiple machines for large environments + +## Supported connectors + +Scanners are available for the following connectors: + +- Active Directory +- File Server (all supported file server types) + +Entra ID and SharePoint Online connectors connect directly from the Access Analyzer service and don't use scanners. + +## Architecture + +Scanners run as Kubernetes Jobs — short-lived containers that start on demand to perform a scan and terminate when the scan completes. There is no persistent agent process running on the scanner host between scans. + +Custom scanner hosts join the Access Analyzer Kubernetes cluster as worker nodes during deployment. Access Analyzer schedules scan jobs to those nodes using standard Kubernetes job dispatch. The scanner host needs outbound connectivity to the Access Analyzer server on port 6443 (Kubernetes API) to receive and run jobs. + +This is a different architecture from the Proxy and Applet modes in legacy Netwrix Access Analyzer (NAA) v12: + +| | Legacy NAA (v12) | Access Analyzer | +|---|---|---| +| Distributed scanning | Proxy server / applet deployment | Kubernetes-deployed scanner containers | +| Deployment model | Manual, persistent agent | On-demand Kubernetes Jobs | +| Supported targets | All file system types | Active Directory, all supported file server types | + +## Scanner labels + +Labels are key-value pairs you assign to custom scanners. Source groups use labels to target specific scanners or scanner pools — scans from that source group run only on scanners that carry matching labels. + +Labels let you: + +- Isolate scan traffic by environment (`environment=production`, `environment=staging`) +- Route scans to geographically local scanners (`region=us-east`, `region=eu-west`) +- Dedicate scanners to high-sensitivity source groups (`tier=restricted`) + +At least one label is required on every custom scanner. Multiple scanners can share the same label — when a source group targets a label that multiple scanners carry, any of those scanners can run the job. + +The system scanner does not use labels. Selecting **System scanner** in a source group always uses the built-in scanner on the Access Analyzer server. + +## Related pages + +- [Requirements](./requirements.md) — System requirements for deploying a custom scanner +- [Deploy a Scanner](./deploy-scanner.md) — Register a new custom scanner +- [Manage Scanners](./manage-scanners.md) — View health, edit, and delete scanners +- [Best Practices](./best-practices.md) — Labeling schemes, concurrency, and naming conventions diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scanners/requirements.md b/docs/accessanalyzer/2601/configurations/source-groups/scanners/requirements.md new file mode 100644 index 0000000000..841765cb9d --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scanners/requirements.md @@ -0,0 +1,77 @@ +--- +title: "Scanner Requirements" +description: "System requirements and prerequisites for deploying a custom scanner in Access Analyzer" +sidebar_position: 20 +--- + +# Scanner Requirements + +These requirements apply to any Linux host you want to register as a custom scanner. The system scanner built into Access Analyzer has no additional requirements. + +## Operating system + +Access Analyzer supports any Linux distribution as a scanner host. Ubuntu 20.04 LTS or later is recommended. + +Access Analyzer registers the scanner by connecting over SSH and running an automated installation script. The script installs [k3s](https://k3s.io/) — a lightweight Kubernetes distribution — and joins the host to the Access Analyzer cluster as a worker node. + +## Hardware + +| Resource | Minimum | +|----------|---------| +| CPU | 2 cores | +| Available RAM | 512 MB | +| Free disk space | 5 GB (on `/`) | + +## Software and access + +The registration script runs automatically over SSH. Before registering a scanner, confirm the following on the target host: + +- `curl` is installed +- `bash` is installed +- The SSH service account used during registration has passwordless `sudo` access + +### Preflight checks + +When you click **Deploy** in the Deploy Scanner wizard, Access Analyzer runs the following preflight checks on the target host before installing k3s. All checks must pass for registration to proceed. + +| Check | Requirement | +|-------|-------------| +| `curl` available | `curl` must be installed and on the system PATH | +| `bash` available | `bash` must be installed and on the system PATH | +| Passwordless sudo | The SSH service account must be able to run `sudo` without a password prompt | +| Internet access | The host must be able to reach `https://get.k3s.io` to download the k3s installer | +| Disk space | At least 5 GB free on `/` | +| Memory | At least 512 MB available RAM | +| CPU | At least 2 CPU cores | + +## Network requirements + +### Ports + +| Port | Protocol | Direction | Purpose | +|------|----------|-----------|---------| +| 22 | TCP | Access Analyzer → Scanner | SSH connection during registration only | +| 6443 | TCP | Scanner → Access Analyzer | Kubernetes API — ongoing job dispatch | + +Port 22 is only required during the initial registration. After the scanner is registered, the scanner host connects outbound to the Access Analyzer server on port 6443 to receive and run scan jobs. Port 22 can be restricted or closed after registration is complete. + +:::note +The SSH port defaults to **22** but is configurable in the Deploy Scanner wizard. If your scanner host runs SSH on a non-standard port, enter it in the **SSH Port** field during deployment. +::: + +### Internet access + +The registration script downloads the k3s installer from `https://get.k3s.io`. The scanner host must be able to reach this URL **during registration only**. After registration completes, internet access is not required for normal scan operation. + +## Service account + +Scanner deployment requires an **SSH Username / SSH Key** service account in Access Analyzer. This account must: + +- Have SSH access to the scanner host +- Use an **unencrypted** private key in PEM format + +:::warning +Passphrase-protected private keys are not supported. The registration script will fail if the key requires a passphrase. Use a key generated without a passphrase, or strip the passphrase before creating the service account. +::: + +See [SSH Username / SSH Key](../../service-accounts/ssh-username-key.md) to create this account. You can also create it inline from the Deploy Scanner wizard using the **+** button next to the Service Account field without navigating away. diff --git a/docs/accessanalyzer/2601/configurations/source-groups/scans.md b/docs/accessanalyzer/2601/configurations/source-groups/scans.md new file mode 100644 index 0000000000..9fcb677e43 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/scans.md @@ -0,0 +1,108 @@ +--- +title: "Scans" +description: "Scan types, configuration, scheduling, and scan location in Access Analyzer source groups" +sidebar_position: 2 +--- + +# Scans + +A scan defines what Access Analyzer collects from a source and how often it runs. Each source in a group can have one or more scans, one per scan type. Scans are persistent configurations — each run of a scan produces a [scan execution](scan-executions.md). + +## Scan types + +The scan types available depend on the source type: + +| Source Type | Available Scan Types | +| --- | --- | +| **File Server** | Access Scan, Sensitive Data Scan | +| **SharePoint Online** | Access Scan, Sensitive Data Scan | +| **Active Directory** | Active Directory Inventory | +| **Entra ID** | Users, Groups and Roles | + +### Access Scan + +Enumerates permissions, folder-level ACLs, sharing links, and access rights across File Server and SharePoint Online sources. Identifies who has access to what across your data sources. + +Access scans include a **concurrent** option that allows multiple file paths or objects within a single source to be scanned in parallel. Enable this when scanning large file servers or SharePoint sites to reduce total scan time. + +### Sensitive Data Scan + +Classifies file and document content against the detection patterns configured under **Configuration** > **Sensitive Data**. Identifies files containing PII, PHI, credentials, financial records, and other sensitive data across File Server and SharePoint Online sources. + +Sensitive Data Scans include a **concurrent** option that allows classification to run against multiple files simultaneously within a single source. Enable this on sources with large file counts to improve throughput. + +### Active Directory Inventory + +Synchronizes users, groups, group memberships, and security-relevant attributes from Active Directory domains. The inventory is used to resolve identity information across all other scan types and to populate the Active Directory dashboard. + +### Users, Groups and Roles + +Synchronizes users, groups, and role assignments from your Microsoft Entra ID (Azure AD) tenant. This scan type also collects Microsoft Information Protection (MIP) sensitivity labels applied across the tenant. + +## Scan configuration + +When you create a source group, the setup wizard collects scan parameters on page 3 and creates scan configurations that apply to all sources added to the group. Each scan configuration includes: + +- **Scan type** — the type of scan to run (see [Scan types](#scan-types) above) +- **Concurrent** — whether to parallelize scanning within a single source (Access Scan and Sensitive Data Scan only) +- **Scan location** — which scanner handles the scan (see [Scan location](#scan-location) below) +- **Schedule** — when and how often the scan runs automatically (see [Schedule](#schedule) below) +- **Scan parameters** — source-type-specific settings such as scope, depth, and included paths. These vary by connector. + +Individual sources can override the group-level scan configuration if their requirements differ from the group default. + +## Scan location + +The **Scan location** setting determines which scanner component executes the scan. It is configured per scan type during source group creation. + +| Location | Description | Applicable Source Types | +| --- | --- | --- | +| **System scanner** | The Access Analyzer service connects directly to the source. This is the default and requires no additional configuration. | Entra ID, SharePoint Online | +| **Scanner label** | Routes the scan to a registered edge scanner pool that matches the specified label. The edge scanner connects to the source on behalf of Access Analyzer. | Active Directory, File Server | + +For Active Directory and File Server source groups, selecting a scanner label routes all scans in that group to the matching edge scanner pool. If no edge scanners are registered with that label, the scan cannot run. See [Scanners](scanners/overview.md) for setup and label management. + +:::note +Entra ID and SharePoint Online source groups always use the system scanner. The scan location setting is not configurable for those source types. +::: + +## Schedule + +The schedule determines when a scan runs automatically. You configure the schedule on page 3 of the source group creation wizard. The same scheduling options are available for all source types and scan types. + +### Scheduling options + +| Option | Description | +| --- | --- | +| **Run scan now** | Starts the scan immediately when the source group is saved. No recurring schedule is set. | +| **Run scan at** | Schedules a single one-time run at a specific date and time. The scan does not repeat after that run. | +| **Advanced** | Sets a recurring schedule using a cron expression. Use this for daily, weekly, or custom interval schedules. | + +### Cron schedule format + +Advanced scheduling uses standard 5-field cron syntax: + +``` +┌───── minute (0–59) +│ ┌───── hour (0–23) +│ │ ┌───── day of month (1–31) +│ │ │ ┌───── month (1–12) +│ │ │ │ ┌───── day of week (0–6, Sunday = 0) +│ │ │ │ │ +* * * * * +``` + +**Examples:** + +| Expression | Schedule | +| --- | --- | +| `0 2 * * *` | Daily at 2:00 AM | +| `0 2 * * 0` | Weekly on Sunday at 2:00 AM | +| `0 2 1 * *` | Monthly on the 1st at 2:00 AM | +| `0 */6 * * *` | Every 6 hours | + +Schedule times are evaluated in the server's local timezone. + +:::note +If no schedule is configured, the scan does not run automatically. Run it manually from the source groups list using the **Run** action. +::: diff --git a/docs/accessanalyzer/2601/configurations/source-groups/source-groups.md b/docs/accessanalyzer/2601/configurations/source-groups/source-groups.md new file mode 100644 index 0000000000..52296d36e7 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/source-groups/source-groups.md @@ -0,0 +1,100 @@ +--- +title: "Source Groups" +description: "Managing source groups in Access Analyzer — create, configure, and operate groups of data sources" +sidebar_position: 1 +--- + +# Source Groups + +A source group is a named container that organizes data sources of the same type for coordinated scanning. All sources in a group share a service account, and you can run or stop scans across all sources in the group with a single action. + +Navigate to **Configuration** > **Source Groups** to view, create, and manage source groups. + +## Source groups list + +The source groups list displays all configured source groups. Each row shows: + +| Column | Description | +| --- | --- | +| **Name** | The source group name. | +| **Source Type** | The type of data source in the group (Active Directory, File Server, Entra ID, or SharePoint Online). | +| **Service Account** | The service account used to authenticate scans in this group. | +| **Status** | Whether the group is **Active** or **Inactive**. Inactive groups are excluded from scheduled scan runs. | +| **Scan Types** | The scan types configured for this group. Varies by source type — see [Scan types](scans.md#scan-types). | +| **Scanner Labels** | Key-value labels used to route scans to specific scanner pools. Displayed only for Active Directory and File Server groups. | +| **Last Scan** | The timestamp of the most recent completed scan execution across all sources in the group. | + +Use the search field to filter by name. You can sort by any column and filter by source type, status, service account, or scan status. + +## Create a source group + +1. Click **Add Source Group**. +2. Enter a **Name** and optional **Description**. Names must be unique (case-insensitive) and between 1 and 255 characters. +3. Select the **Source Type**. This value is permanent — it can't be changed after the group is created. +4. Select or create a **Service Account**. The wizard filters available accounts to those compatible with the selected source type. To create a new account inline, click **+** next to the field. +5. For Active Directory and File Server groups, optionally add **Scanner Labels** to route scans to a specific scanner pool. See [Scanners](scanners/overview.md). +6. Add sources and configure scan parameters. You can also add sources later from the group detail view. +7. Click **Save**. + +:::warning +Changing the source type is not possible after a source group is created. If you need a different source type, create a new source group and delete the original. +::: + +## Edit a source group + +1. In the source groups list, click the actions menu for a group and select **Edit**. +2. Modify any of the following fields: + - Name and description + - Service account + - Scanner labels + - Status (Active or Inactive) +3. Click **Save**. + +The source type cannot be changed. If you update the service account, the new credentials apply to all future scans in the group — verify the replacement account has the required permissions before saving. + +## Add sources to a group + +1. In the source groups list, click the actions menu for a group and select **View Sources**. +2. Click **Add Source**. +3. Complete the source configuration form. Required fields vary by source type. +4. Click **Save**. + +Sources you add inherit the group's service account and scan configuration unless you override them at the source level. + +## Remove sources from a group + +1. In the source groups list, click the actions menu for a group and select **View Sources**. +2. In the sources drawer, click the actions menu for a source and select **Remove**. + +You can't remove a source that has a scan in a pending, running, pausing, paused, resuming, stopping, or post-processing state. Wait for the scan to complete or stop it first. + +## Run scans + +To start scans across all sources in a group, click the **Run** button in the actions menu for the group. Access Analyzer queues scan executions for every configured scan in the group. + +To run scans for a single source, open the source from the **View Sources** drawer and use the source-level run action. + +## Stop scans + +To stop all running and pending scans in a group, click **Stop** in the actions menu. Access Analyzer sends a stop signal to every active scan execution in the group. Scans in a stopping or post-processing state continue until they reach a terminal state. + +## Delete a source group + +1. In the source groups list, click the actions menu for a group and select **Delete**. +2. Confirm the deletion. + +:::warning +Deleting a source group permanently deletes all sources it contains. This action can't be undone. +::: + +You can't delete a source group while any of its scans are in a pending, running, pausing, paused, resuming, stopping, or post-processing state. Stop all active scans before deleting. + +## Constraints + +| Setting | Constraint | +| --- | --- | +| **Name** | 1–255 characters; must be unique (case-insensitive) across all source groups | +| **Description** | Maximum 10,000 characters | +| **Source type** | Set at creation; can't be changed afterward | +| **Delete** | Blocked while any source has an active scan execution | +| **Remove source** | Blocked while that source has an active scan execution | diff --git a/docs/accessanalyzer/2601/configurations/users.md b/docs/accessanalyzer/2601/configurations/users.md new file mode 100644 index 0000000000..12a141c834 --- /dev/null +++ b/docs/accessanalyzer/2601/configurations/users.md @@ -0,0 +1,176 @@ +--- +title: "Users" +description: "Managing users in the Configuration node" +sidebar_position: 70 +--- + +# Users + +The Users page lets you create and manage the accounts that have access to Netwrix Access Analyzer. Navigate to **Configuration** > **Users** to view and manage all users. + +:::note +This page is available to users with the **User Admin** or **Administrator** role. Users with the Viewer role cannot access this page. +::: + +## Users list + +The users list displays all accounts in the system. Each row shows: + +| Column | Description | +| --- | --- | +| **Username** | The display name for the account. | +| **Email** | The email address used to sign in. | +| **Role** | The account's role: **Administrator**, **User Admin**, or **Viewer**. | +| **Status** | Whether the account is **Active** or **Inactive**. | +| **Last Login** | The date of the most recent successful sign-in, or **Never** if the user hasn't signed in yet. | + +Use the search field to filter by name or email. You can sort by any column. + +## Roles + +Access Analyzer has three roles: + +| Role | Description | +| --- | --- | +| **Administrator** | Full access: system configuration (sources, scans, connectors, application settings) and user management (create, edit, activate, deactivate, and delete users; assign roles; pre-provision federated users). | +| **User Admin** | User and role management rights only: create, edit, activate, deactivate, and delete users; assign roles; pre-provision federated users. Does **not** have system configuration rights. | +| **Viewer** | Read-only access to data and reports. No configuration or user management rights. | + +A user can only hold one role at a time. + +## Bootstrap admin account + +Access Analyzer seeds a built-in account, `admin@dspm.local`, during installation. This account is assigned the **User Admin** role and is intended for first-time user provisioning only. + +To retrieve the bootstrap admin password: + +```bash +sudo kubectl get secret -n access-analyzer dspm-bootstrap-admin \ + -o jsonpath='{.data.password}' | base64 -d; echo +``` + +On first login, you will be prompted to enroll an authenticator app for MFA and set a display name. Do not change the email address. + +:::note +Keep the bootstrap account active as an emergency recovery account, but do not use it for routine user management. Create at least one named User Admin account during initial setup and use that account for ongoing administration. +::: + +For the full first-login walkthrough, see [Quick Install — Step 5](/docs/accessanalyzer/2601/install/quickinstall#step-5-sign-in-as-the-bootstrap-user-admin-and-pre-provision-users). + +## Recommended initial setup + +After installation, complete the following steps in order before handing the product to your team. + +| Step | Action | Notes | +| --- | --- | --- | +| **1** | Sign in as `admin@dspm.local` | Uses the bootstrap User Admin account. Retrieve the password using the kubectl command above. | +| **2** | Create at least one named **User Admin** | Provides a dedicated account for user management with no system configuration access. Use this account for ongoing user administration so that Administrator accounts are not required for routine user changes. | +| **3** | Create at least one **Administrator** | Grants full access — system configuration and user management. This is typically the person responsible for setting up and maintaining the product. | +| **4** | Create **Viewer** accounts as needed | Optional. Add Viewer accounts for stakeholders who need read-only access to dashboards and reports. | +| **5** | Sign out of the bootstrap account | Day-to-day work should be done from named accounts. | + +## Add a user + +The form for adding a user differs depending on whether your deployment uses an external Identity Provider (IdP) for authentication. + +### Add a user (local authentication) + +Use this procedure when Access Analyzer manages passwords directly. + +1. Click **Add User**. +2. Enter a **Name**. Names must be between 2 and 100 characters. +3. Enter an **Email** address. Email addresses must be unique across all users (case-insensitive). +4. Select a **Role**: **Administrator**, **User Admin**, or **Viewer**. The default is **Viewer** — the intentionally conservative default. Only assign Administrator or User Admin after confirming the user's responsibilities. +5. Enter a **Password** and confirm it. +6. Click **Create User**. + +Password requirements for local accounts: + +- Minimum 18 characters +- At least one uppercase letter (A–Z) +- At least one lowercase letter (a–z) +- At least one number (0–9) +- At least one special character (`!@#$%^&*(),.?":{}|<>`) +- Can't contain the user's email address +- Can't be a commonly used password + +### Add a user (Identity Provider) + +When your deployment is configured to use an external Identity Provider, you can pre-provision an account before the user's first sign-in. Access Analyzer creates the account record and links it to the user's IdP identity when they sign in for the first time. + +1. Click **Add User**. +2. Enter a **Name**. Names must be between 2 and 100 characters. +3. Enter an **Email** address. The email must match the address the user has in your IdP exactly, including case. +4. Select a **Role**: **Administrator**, **User Admin**, or **Viewer**. The default is **Viewer** — the intentionally conservative default. Only assign Administrator or User Admin after confirming the user's responsibilities. +5. Click **Create User**. + +No password is required. The account is ready for the user to sign in through your IdP. + +:::note +If a user authenticates through your IdP without a pre-provisioned account in Access Analyzer, their sign-in is blocked and they see an access error. Pre-provision the account first, then the user can sign in successfully. +::: + +## Edit a user + +1. In the users list, click the actions menu for a user and select **Edit**. +2. Modify the fields as needed. +3. Click **Update User**. + +What you can change depends on the account type: + +| Account type | Editable fields | +| --- | --- | +| Local (password-based) | Name, Email, Role | +| Identity Provider — pre-provisioned (hasn't signed in yet) | Name, Email, Role | +| Identity Provider — provisioned (has signed in at least once) | Role only | + +Name and email are locked for provisioned IdP accounts because those values come from the IdP token. To change them, update the user's profile in your IdP. + +## Activate a user + +1. In the users list, click the actions menu for an inactive user and select **Activate**. + +The account becomes active immediately. The user can sign in and use the application according to their assigned role. + +## Deactivate a user + +1. In the users list, click the actions menu for an active user and select **Deactivate**. + +Deactivating a user revokes all of their active sessions immediately. The account record is preserved and can be reactivated later. + +:::note +You can't deactivate your own account or the last active User Admin account. +::: + +## Reset a user's password + +:::note +The **Reset Password** action is available for local accounts only. It doesn't appear for accounts that authenticate through an Identity Provider. +::: + +1. In the users list, click the actions menu for a user and select **Reset Password**. + +Access Analyzer generates a password reset token for the user. The user must set a new password before they can sign in again. Reset tokens expire after 2 hours. + +## Delete a user + +1. In the users list, click the actions menu for a user and select **Delete**. +2. Confirm the deletion. + +:::warning +Deleting a user is permanent and can't be undone. +::: + +You can't delete your own account or the last active User Admin account. + +## Constraints + +| Setting | Constraint | +| --- | --- | +| **Name** | 2–100 characters | +| **Email** | Must be unique across all users (case-insensitive); must be a valid email address | +| **Role** | Administrator, User Admin, or Viewer; defaults to Viewer | +| **Password** | Minimum 18 characters; must include uppercase, lowercase, number, and special character; can't match the user's email; can't be a commonly used password | +| **Deactivate** | Blocked for your own account and the last active User Admin | +| **Delete** | Blocked for your own account and the last active User Admin | +| **Reset Password** | Local accounts only; tokens expire after 2 hours | diff --git a/docs/accessanalyzer/2601/connectors/_category_.json b/docs/accessanalyzer/2601/connectors/_category_.json new file mode 100644 index 0000000000..67fabb3b53 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Connector Requirements", + "position": 14, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/connectors/activedirectory.md b/docs/accessanalyzer/2601/connectors/activedirectory.md new file mode 100644 index 0000000000..fc76232824 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/activedirectory.md @@ -0,0 +1,48 @@ +--- +title: "Active Directory" +description: "Requirements for the Active Directory connector" +sidebar_position: 30 +--- + +# Active Directory + +The Active Directory connector reads domain controllers remotely over LDAP to collect identity data from your Active Directory domains. The connector doesn't require agent installation on domain controllers. + +The connector collects: + +- Users (including disabled and stale accounts) +- Groups and group memberships (including nested groups and circular membership chains) +- Domains + +## Supported versions + +- Windows Server 2016 and later +- Windows Server 2003 forest functional level or higher + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must be a member of the domain you're scanning and have: + +- Read access to the directory tree +- List Contents and Read Property on the Deleted Objects container + +:::note +For information on granting access to the Deleted Objects container, see the Microsoft [Searching for Deleted Objects](https://technet.microsoft.com/en-us/library/cc978013.aspx) article and [Dsacls](https://technet.microsoft.com/en-us/library/cc771151(v=ws.11).aspx) reference. +::: + +### Ports + +Open the following ports on all domain controllers you want to scan: + +| Port | Protocol | Description | +|------|----------|-------------| +| 389 | TCP | LDAP | +| 636 | TCP | LDAPS (when SSL is enabled) | +| 135–139 | TCP | RPC | +| 49152–65535 | TCP | RPC dynamic ports | + +## Next steps + +Once requirements are met, see [Set Up Active Directory Source Group](../gettingstarted/active-directory/set-up-source-group.md) to configure your first scan. diff --git a/docs/accessanalyzer/2601/connectors/entra-id/_category_.json b/docs/accessanalyzer/2601/connectors/entra-id/_category_.json new file mode 100644 index 0000000000..83c1bf103d --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/entra-id/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Entra ID", + "position": 30, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/connectors/entra-id/app-registration-secret.md b/docs/accessanalyzer/2601/connectors/entra-id/app-registration-secret.md new file mode 100644 index 0000000000..8e52193448 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/entra-id/app-registration-secret.md @@ -0,0 +1,54 @@ +--- +title: "Client Secret Configuration" +description: "Configure a client secret for the Microsoft Entra ID app registration" +sidebar_position: 30 +--- + +# Client Secret Configuration + +Access Analyzer authenticates to Microsoft Entra ID using a client secret. The client secret is generated within your registered Microsoft Entra ID application and provided to Access Analyzer when configuring the Entra ID connector. + +## Generate a client secret + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. Navigate to **Identity** > **Applications** > **App registrations**. + +3. Click the **All applications** tab and select your registered application. + +4. Click **Certificates & secrets** under the Manage section. + +5. On the **Client secrets** tab, click **New client secret**. + +6. Specify the following: + + - **Description** — Enter a description for the secret + - **Expires** — Select an expiration period + +7. Click **Add**. The client secret value is displayed in the **Value** column. + +:::warning +Copy the client secret value immediately. Once you navigate away from this page, the value can't be retrieved and you'll need to create a new secret. +::: + +## Assign roles to the app + +The registered application must be assigned to the **Global Administrator** role for Entra ID data collection. + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. Navigate to **Identity** > **Applications** > **App registrations**. + +3. Click the **All applications** tab and select your registered application. + +4. Click **Roles and administrators** under the Manage section. + +5. On the All roles page, search for **Global Administrator**. + +6. Click the **Global Administrator** role. The Assignments page opens. + +7. Click **Add assignments** in the top toolbar. + +8. Search for and select your registered application. + +9. Click **Add**. The application is listed on the Assignments page. diff --git a/docs/accessanalyzer/2601/connectors/entra-id/entra-requirements.md b/docs/accessanalyzer/2601/connectors/entra-id/entra-requirements.md new file mode 100644 index 0000000000..cd4c6be7bf --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/entra-id/entra-requirements.md @@ -0,0 +1,66 @@ +--- +title: "Entra tenant requirements" +description: "Configure Microsoft Entra ID requirements for connectivity" +sidebar_position: 20 +--- + +# Entra tenant requirements + +Access Analyzer connects to Microsoft Entra ID through a registered application using OAuth2 client credentials. You must register a dedicated Microsoft Entra ID application for Access Analyzer and grant it the required permissions before adding Entra ID as a data source. + +:::note +A user account with the **Global Administrator**, **Application Administrator**, or **Cloud Application Administrator** role is required to register an application and grant admin consent for permissions. +::: + +:::note +The registered application must be assigned to the **Global Administrator** role for Entra ID data collection. +::: + +## Register an app in Microsoft Entra ID + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. On the left navigation menu, navigate to **Identity** > **Applications** > **App registrations**. + +3. On the App registrations page, click **New registration** in the top toolbar. + +4. Specify the following on the Register an application page: + + - **Name** — Enter a display name for the application, for example, *Access Analyzer Entra ID* + - **Supported account types** — Select **Accounts in this organizational directory only** + - **Redirect URI (optional)** — Leave blank + +5. Click **Register**. + +The Overview page for the newly registered application opens. Copy the following values — you'll need them when configuring the Entra ID connector in Access Analyzer: + +- **Application (client) ID** +- **Directory (tenant) ID** + +## Grant permissions to the app + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. Navigate to **Identity** > **Applications** > **App registrations**. + +3. Click the **All applications** tab and select the application you registered. + +4. Click **API permissions** under the Manage section. + +5. Click **Add a permission**. The Request API permissions pane opens. + +6. Click **Microsoft Graph**, then click the **Application permissions** tab. + +7. Select the required permissions (see table below). + +8. Click **Add Permissions**. + +9. Click **Grant admin consent for ``** to apply the permissions. + +### Required permissions + +| API | Permission | Description | +| --- | --- | --- | +| Microsoft Graph | `Directory.Read.All` | Read directory data — users, groups, and role assignments | +| Microsoft Graph | `Policy.Read.All` | Read your organization's policies | +| Microsoft Graph | `InformationProtectionPolicy.Read.All` | Read your organization's information protection policies — required for MIP label retrieval | diff --git a/docs/accessanalyzer/2601/connectors/entra-id/overview.md b/docs/accessanalyzer/2601/connectors/entra-id/overview.md new file mode 100644 index 0000000000..fd2a7c368a --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/entra-id/overview.md @@ -0,0 +1,38 @@ +--- +title: "Entra ID" +description: "Requirements for connecting Access Analyzer to Microsoft Entra ID" +sidebar_position: 1 +--- + +# Entra ID + +Access Analyzer connects to Microsoft Entra ID using OAuth2 client credentials through a pre-configured Microsoft Entra ID application. It accesses Entra ID through Microsoft Graph to synchronize users, groups, role assignments, and Microsoft Information Protection (MIP) sensitivity labels. + +Before adding Entra ID as a data source, you must register a dedicated Microsoft Entra ID application and grant it the required permissions. + +## Scan types + +| Scan type | Description | +| --- | --- | +| **Users, Groups, and Roles** | Synchronizes users, groups, and role assignments from the Entra ID tenant. The first scan runs in full; subsequent scans collect only changes since the last run. Also retrieves MIP sensitivity labels automatically when the scan runs. | + +## Before you begin + +You need the following before adding Entra ID as a data source: + +- A user account with the **Global Administrator**, **Application Administrator**, or **Cloud Application Administrator** role in Microsoft Entra ID, to register an application and grant admin consent for permissions +- A registered Microsoft Entra ID application with the required API permissions — see [Entra Tenant Requirements](entra-requirements.md) +- A client secret generated for the registered application — see [Client Secret Configuration](app-registration-secret.md) + +When configuring the Entra ID source in Access Analyzer, you need the following values from your registered application: + +- **Application (client) ID** +- **Directory (tenant) ID** +- **Client secret value** + +## Network requirements + +| Protocol | Port | Destination | +| --- | --- | --- | +| HTTPS | 443 | Microsoft identity platform (`login.microsoftonline.com`) | +| HTTPS | 443 | Microsoft Graph API (`graph.microsoft.com`) | diff --git a/docs/accessanalyzer/2601/connectors/file-servers/_category_.json b/docs/accessanalyzer/2601/connectors/file-servers/_category_.json new file mode 100644 index 0000000000..5923518b84 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "File Servers", + "position": 20, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/connectors/file-servers/celerra.md b/docs/accessanalyzer/2601/connectors/file-servers/celerra.md new file mode 100644 index 0000000000..2af864e745 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/celerra.md @@ -0,0 +1,36 @@ +--- +title: "Dell EMC Celerra" +description: "Supported platforms, permissions, and network ports for Dell EMC Celerra CIFS/SMB scanning" +sidebar_position: 50 +--- + +# Dell EMC Celerra + +The Dell EMC Celerra connector reads file shares over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the storage system. + +Dell EMC Celerra serves CIFS/SMB file shares through Data Movers. The CIFS service must be licensed and configured on each Data Mover you want to scan. + +## Supported versions + +- Celerra series (DART OS 6.x and later) + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +The account can be a local user on the Data Mover or a domain account from an Active Directory domain joined to the Data Mover. + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a Dell EMC Celerra Data Mover to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). Add each Data Mover as a separate server entry using its IP address or hostname. The connector connects to each Data Mover independently. diff --git a/docs/accessanalyzer/2601/connectors/file-servers/cifs.md b/docs/accessanalyzer/2601/connectors/file-servers/cifs.md new file mode 100644 index 0000000000..19aa9567af --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/cifs.md @@ -0,0 +1,41 @@ +--- +title: "CIFS / SMB File Share" +description: "Supported platforms, permissions, and network ports for CIFS/SMB scanning" +sidebar_position: 10 +--- + +# CIFS / SMB File Share + +The CIFS / SMB connector reads file servers over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the target file server. + +## Supported versions + +- Windows Server 2012 R2 and later +- Any SMB-compatible server (Samba, network-attached storage (NAS) appliances) + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a Windows file server or SMB-compatible server to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). + +## DFS namespaces + +For domain-based Distributed File System (DFS) namespaces, the scan targets the default domain controller for the domain. For standalone namespaces or multiple namespaces, add the server or servers hosting the namespace directly to the source group. + +## Sensitive Data Discovery + +Sensitive Data Discovery (SDD) is handled by the scanner infrastructure. No additional software is required on the target file server. diff --git a/docs/accessanalyzer/2601/connectors/file-servers/dell-unity.md b/docs/accessanalyzer/2601/connectors/file-servers/dell-unity.md new file mode 100644 index 0000000000..42062d1235 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/dell-unity.md @@ -0,0 +1,36 @@ +--- +title: "Dell Unity" +description: "Supported platforms, permissions, and network ports for Dell Unity CIFS/SMB scanning" +sidebar_position: 40 +--- + +# Dell Unity + +The Dell Unity connector reads file shares over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the storage system. + +Dell Unity serves CIFS/SMB shares through NAS servers. The CIFS protocol must be configured on each NAS server you want to scan. + +## Supported versions + +- Unity OE 4.x and later + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +The account can be a local user on the NAS server or a domain account from an Active Directory domain joined to the NAS server. + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a Dell Unity NAS server to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). Add each NAS server as a separate server entry using its IP address or hostname. The connector connects to each NAS server independently. diff --git a/docs/accessanalyzer/2601/connectors/file-servers/isilon-powerscale.md b/docs/accessanalyzer/2601/connectors/file-servers/isilon-powerscale.md new file mode 100644 index 0000000000..bd212a1748 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/isilon-powerscale.md @@ -0,0 +1,36 @@ +--- +title: "Dell Isilon / PowerScale" +description: "Supported platforms, permissions, and network ports for Dell Isilon and PowerScale CIFS/SMB scanning" +sidebar_position: 30 +--- + +# Dell Isilon / PowerScale + +The Dell Isilon / PowerScale connector reads file shares over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the storage system. + +Dell Isilon / PowerScale (based on the OneFS operating system) organizes SMB shares within access zones. The SMB service must be enabled on each access zone you want to scan. + +## Supported versions + +- OneFS 8.0 and later + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +The account can be a local user on the OneFS cluster or a domain account from an Active Directory domain joined to the access zone. + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a Dell Isilon / PowerScale access zone to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). Add each access zone as a separate server entry using the access zone's IP address or hostname. The connector connects to each access zone independently. diff --git a/docs/accessanalyzer/2601/connectors/file-servers/netapp.md b/docs/accessanalyzer/2601/connectors/file-servers/netapp.md new file mode 100644 index 0000000000..ec02a17fee --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/netapp.md @@ -0,0 +1,41 @@ +--- +title: "NetApp ONTAP" +description: "Supported platforms, permissions, and network ports for NetApp ONTAP CIFS/SMB scanning" +sidebar_position: 20 +--- + +# NetApp ONTAP + +The NetApp ONTAP connector reads file shares over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the storage system. + +NetApp ONTAP serves CIFS/SMB shares through Storage Virtual Machines (SVMs). Each SVM has its own CIFS server that the connector connects to independently. The CIFS service must be licensed and enabled on each SVM you want to scan. + +## Supported versions + +- ONTAP 9.0 and later +- ONTAP 8.3 with CIFS license + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +The account can be a local ONTAP user or a domain account from an Active Directory domain joined to the SVM. + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a NetApp ONTAP SVM to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). Add each SVM as a separate server entry using the SVM's CIFS server hostname or IP address. The connector connects to each SVM independently. + +## Known behavior + +NetApp ONTAP may return invalid timestamp values on some systems due to a Year 2038 overflow issue in the ONTAP CIFS implementation. Access Analyzer detects and handles this automatically — affected timestamps are recorded as empty rather than causing a scan error. diff --git a/docs/accessanalyzer/2601/connectors/file-servers/vnx.md b/docs/accessanalyzer/2601/connectors/file-servers/vnx.md new file mode 100644 index 0000000000..aec64b98c6 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/file-servers/vnx.md @@ -0,0 +1,39 @@ +--- +title: "Dell EMC VNX" +description: "Supported platforms, permissions, and network ports for Dell EMC VNX file server CIFS/SMB scanning" +sidebar_position: 60 +--- + +# Dell EMC VNX + +The Dell EMC VNX connector reads file shares over SMB to collect share permissions, folder and file ACLs, and file contents for sensitive data classification. The connector doesn't require agent installation on the storage system. + +Dell EMC VNX serves CIFS/SMB file shares through Data Movers. The CIFS service must be licensed and configured on each Data Mover you want to scan. + +## Supported versions + +- VNX2 series (NAS code 8.x) +- VNX series (NAS code 7.x) + +VNX2 is the second-generation platform; VNX is the original series. Both use the same Data Mover architecture and are configured identically in Access Analyzer. + +## Requirements + +### Service account + +The connector authenticates using a service account with a username and password. The account must have: + +- Read access to the shares you want to scan +- Read permission on object security descriptors (to enumerate ACLs) + +The account can be a local user on the Data Mover or a domain account from an Active Directory domain joined to the Data Mover. + +### Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 445 | TCP | SMB file sharing | + +## Set up + +To add a Dell EMC VNX Data Mover to Access Analyzer, see [Set Up File Server Source Group](../../gettingstarted/file-servers/set-up-source-group.md). Add each Data Mover as a separate server entry using its IP address or hostname. The connector connects to each Data Mover independently. diff --git a/docs/accessanalyzer/2601/connectors/sharepoint-online/_category_.json b/docs/accessanalyzer/2601/connectors/sharepoint-online/_category_.json new file mode 100644 index 0000000000..aebbe26706 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/sharepoint-online/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "SharePoint Online", + "position": 50, + "collapsed": true, + "collapsible": true, + "link": { + "type": "doc", + "id": "connectors/sharepoint-online/overview" + } +} diff --git a/docs/accessanalyzer/2601/connectors/sharepoint-online/azure-permissions.md b/docs/accessanalyzer/2601/connectors/sharepoint-online/azure-permissions.md new file mode 100644 index 0000000000..08002986af --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/sharepoint-online/azure-permissions.md @@ -0,0 +1,64 @@ +--- +title: "App Permissions in Entra" +description: "Configure Microsoft Entra ID app permissions for SharePoint Online connectivity" +sidebar_position: 10 +--- + +# App Permissions in Entra + +Access Analyzer connects to SharePoint Online through a Microsoft Entra ID registered application using certificate-based authentication. You must register a dedicated application for Access Analyzer and grant it the required API permissions before adding SharePoint Online as a data source. + +:::note +A user account with the Global Administrator, Application Administrator, or Cloud Application Administrator role is required to register an application and grant admin consent for permissions. +::: + +## Register an app in Microsoft Entra ID + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. On the left navigation menu, navigate to **Identity** > **Applications** > **App registrations**. + +3. On the App registrations page, click **New registration** in the top toolbar. + +4. Specify the following on the Register an application page: + + - **Name** — Enter a display name for the application, for example, *Access Analyzer SharePoint Online* + - **Supported account types** — Select **Accounts in this organizational directory only** + - **Redirect URI (optional)** — Leave blank + +5. Click **Register**. + +The Overview page for the newly registered application opens. Note the following values — you'll need them when configuring the SharePoint Online connector in Access Analyzer: + +- **Application (client) ID** +- **Directory (tenant) ID** + +## Grant permissions to the app + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. Navigate to **Identity** > **Applications** > **App registrations**. + +3. Click the **All applications** tab and select the application you registered. + +4. Click **API permissions** under the Manage section. + +5. Click **Add a permission**. The Request API permissions pane opens. + +6. Click an API to access its permissions, then click the **Application permissions** tab. + +7. Select the required permissions for each API (see table below). + +8. Click **Add Permissions**. + +9. Repeat steps 6–8 for each API listed in the table. + +10. Click **Grant admin consent for ``** to apply the permissions. + +### Required permissions + +| API | Permission | Description | +| --- | --- | --- | +| Microsoft Graph | `Sites.FullControl.All` | Full control of all site collections | +| Microsoft Graph | `Directory.Read.All` | Read directory data | +| SharePoint | `Sites.FullControl.All` | Full control of all site collections | diff --git a/docs/accessanalyzer/2601/connectors/sharepoint-online/overview.md b/docs/accessanalyzer/2601/connectors/sharepoint-online/overview.md new file mode 100644 index 0000000000..b0c4878e7c --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/sharepoint-online/overview.md @@ -0,0 +1,35 @@ +--- +title: "SharePoint Online" +description: "Requirements for connecting Access Analyzer to SharePoint Online" +sidebar_position: 1 +--- + +# SharePoint Online + +Access Analyzer connects to SharePoint Online using certificate-based authentication through a pre-configured Microsoft Entra ID application. It accesses SharePoint Online through Microsoft Graph and the SharePoint REST API to enumerate sites, libraries, permissions, and sharing links. + +Before adding SharePoint Online as a data source, you must register a dedicated Microsoft Entra ID application, grant it the required permissions, and upload a certificate generated by Access Analyzer. + +## Scan types + +Access Analyzer supports two scan types for SharePoint Online: + +| Scan type | Description | +| --- | --- | +| **Access scan** | Enumerates sites, document libraries, folders, and files. Collects permissions, ACLs, sharing links, and Microsoft Information Protection (MIP) sensitivity labels applied to SharePoint items. The first scan runs in full; subsequent scans collect only changes since the last run. | +| **Sensitive Data scan** | Reads file contents to classify sensitive data. Requires a completed Access scan — it uses the site and file inventory from the Access scan as its input. | + +## Before you begin + +You need the following before adding SharePoint Online as a data source: + +- A user account with the **Global Administrator**, **Application Administrator**, or **Cloud Application Administrator** role in Microsoft Entra ID, to register an application and grant admin consent for permissions +- A registered Microsoft Entra ID application with the required API permissions — see [App Permissions in Entra](azure-permissions.md) +- Access to the Microsoft Entra admin center to upload the certificate generated during source group setup — see [Certificate Configuration](tenant-certificate-config.md) + +When configuring the SharePoint Online source in Access Analyzer, you need the following values from your registered application: + +- **Application (client) ID** +- **Directory (tenant) ID** + +The certificate is generated by Access Analyzer during source group setup. You download it and upload it to your registered Microsoft Entra ID application before the connection can be tested. diff --git a/docs/accessanalyzer/2601/connectors/sharepoint-online/tenant-certificate-config.md b/docs/accessanalyzer/2601/connectors/sharepoint-online/tenant-certificate-config.md new file mode 100644 index 0000000000..8661d4f323 --- /dev/null +++ b/docs/accessanalyzer/2601/connectors/sharepoint-online/tenant-certificate-config.md @@ -0,0 +1,33 @@ +--- +title: "Certificate Configuration" +description: "Upload a certificate to your Microsoft Entra ID app registration for SharePoint Online authentication" +sidebar_position: 20 +--- + +# Certificate Configuration + +Access Analyzer authenticates with SharePoint Online using certificate-based authentication. Access Analyzer generates the certificate during source group setup — you download the public certificate file and upload it to your registered Microsoft Entra ID application. + +## Upload a certificate + +1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +2. Navigate to **Identity** > **Applications** > **App registrations**. + +3. Click the **All applications** tab and select your registered application. + +4. Click **Certificates & secrets** under the Manage section. + +5. Click the **Certificates** tab. + +6. Click **Upload certificate**. + +7. Click the file icon next to the **Select a File** field. + +8. Browse to and select the certificate file you downloaded from Access Analyzer (`.cer` or `.pem`), then click **Open**. + +9. Enter a description for the certificate. + +10. Click **Add**. The certificate is uploaded to the registered application. + +After uploading, return to the Access Analyzer source group wizard and click **Test Connection** to verify the authentication. diff --git a/docs/accessanalyzer/2601/dashboards-reports/_category_.json b/docs/accessanalyzer/2601/dashboards-reports/_category_.json new file mode 100644 index 0000000000..91e8e50995 --- /dev/null +++ b/docs/accessanalyzer/2601/dashboards-reports/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Dashboards and Reports", + "position": 50, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/dashboards-reports/my-reports.md b/docs/accessanalyzer/2601/dashboards-reports/my-reports.md new file mode 100644 index 0000000000..c0b0e171b0 --- /dev/null +++ b/docs/accessanalyzer/2601/dashboards-reports/my-reports.md @@ -0,0 +1,83 @@ +--- +title: "My Reports" +description: "Save, manage, and reload filtered report views in Netwrix Access Analyzer" +sidebar_position: 30 +--- + +# My Reports + +My Reports is a personal workspace for saving filtered report views. When you configure a report with specific filters — a particular share, user, or time range — you can save that configuration as a named report and reload it later without reapplying the filters manually. + +Saved reports are private to the user who created them. Other users can't view or modify your saved reports. + +Navigate to **Reports** > **My Reports** to view your saved reports. + +## Save a report + +You can save any report that has the **Save Report** button in its toolbar. The button appears on File System and SharePoint report pages. + +1. Navigate to the report you want to save — for example, **Reports** > **File System** > **Access**. +2. Select a report type from the selector — for example, **Share Audit**. +3. Apply the filters you want to capture. +4. Click **Save Report** in the toolbar. +5. In the **Save Report** dialog, enter a name for the report. Names are required, must be unique (case-insensitive) within your saved reports, and can't exceed 100 characters. +6. Review the **Current Filters** section to confirm the active filters are correct. +7. Click **Save Report**. + +After saving, Access Analyzer redirects you to **My Reports** where the new report appears in the list. + +:::note +If no filters are applied when you click **Save Report**, the dialog indicates that no filters are active. You can still save the report, but it will open with the default unfiltered view. +::: + +## Open a saved report + +1. Navigate to **Reports** > **My Reports**. +2. In the **My Saved Reports** table, click the row for the report you want to open. + +The report opens with its saved filter configuration applied. A banner at the top of the report displays the report name and a **Back to My Reports** button. + +To return to the **My Reports** list, click **Back to My Reports** in the banner. + +## Rename a saved report + +1. Navigate to **Reports** > **My Reports**. +2. In the **Actions** column for the report you want to rename, click the actions icon (**⋮**). +3. Select **Rename**. +4. Edit the name in the inline text field. The name can't exceed 100 characters. +5. Press **Enter** or click the check icon to save the new name. Press **Escape** or click the X icon to cancel. + +## Delete a saved report + +1. Navigate to **Reports** > **My Reports**. +2. In the **Actions** column for the report you want to delete, click the actions icon (**⋮**). +3. Select **Delete**. + +:::warning +Deleting a saved report is permanent. There's no confirmation step and no undo. +::: + +## My Saved Reports table + +The **My Saved Reports** table lists all reports you've saved. + +| Column | Description | +| --- | --- | +| **Name** | The name of the saved report. Click a row to open the report. | +| **Parent Report** | The report type this was saved from — for example, **Share Audit** or **Broken Inheritance**. Displays a dash if the source can't be identified. | +| **Created** | The date the report was saved. | +| **Actions** | Opens a menu with **Rename** and **Delete** options. | + +When you haven't saved any reports yet, the table displays: + +> *You haven't saved any reports yet. Go to Access, Content, or Activity reports, apply filters, and click "Save Report" to save them here.* + +The table paginates when it contains more than 10 reports. You can display 10 or 25 rows per page. + +## Report name constraints + +| Constraint | Detail | +| --- | --- | +| **Required** | A name is required to save a report. | +| **Maximum length** | 100 characters. | +| **Uniqueness** | Names must be unique within your saved reports (case-insensitive). | diff --git a/docs/accessanalyzer/2601/dashboards-reports/reports.md b/docs/accessanalyzer/2601/dashboards-reports/reports.md new file mode 100644 index 0000000000..aae3642661 --- /dev/null +++ b/docs/accessanalyzer/2601/dashboards-reports/reports.md @@ -0,0 +1,76 @@ +--- +title: "Reports" +description: "All pre-built dashboards and reports available in Netwrix Access Analyzer" +sidebar_position: 10 +--- + +# Reports + +Netwrix Access Analyzer includes pre-built dashboards and reports that surface findings from your scans. Reports become available after the first scan of a source group completes and update each time a scan runs. + +Reports are organized by data source type and grouped by category in the navigation under **Dashboards** and **Reports**. + +## Dashboards + +| Dashboard | Description | +| --- | --- | +| **Data Security** | An overview of data security posture across all connected data sources. | +| **Active Directory** | An overview of Active Directory scan results for one or more domains. Shows inventory counts for users, groups, and group memberships alongside security risk data, including risk breakdowns by type and severity and a ranked list of the objects with the highest number of associated risks. Filter by domain to focus on a specific part of your environment. | + +## File Server reports + +For full details on these reports, see [File Server Reports](/docs/accessanalyzer/2601/gettingstarted/file-servers/reports). + +### Access + +| Report | Description | +| --- | --- | +| **Broken Inheritance** | Lists shares and folders where permission inheritance has been broken, meaning the folder's ACL no longer follows its parent. Use this report to find locations where custom permission assignments may have introduced inconsistencies or unexpected access. | +| **Domain User ACLs** | Shows share and folder permissions assigned directly to domain user accounts. Use this report to identify accounts with direct ACL entries that should be managed through groups instead. | +| **High Risk ACLs** | Identifies folders where broad trustees such as Everyone, Authenticated Users, or Domain Users appear in the access control list. Use this report to locate and remediate over-permissioned folders that expose data to wide audiences. | +| **Local Administrators** | Lists local administrator accounts and the hosts where they hold that privilege. Use this report to identify non-standard or unauthorized local administrator assignments across your file servers. | +| **Missing Full Control** | Lists folders where no trustee holds Full Control permission. Use this report to identify folders that may lack a clear owner or administrator and address potential access management gaps. | +| **Open Access** | Identifies folders and shares accessible to broad groups or where sensitive data is reachable without restriction. Use this report to prioritize remediation of the most exposed locations in your file server environment. | +| **Probable Owner** | Identifies the most likely owner for each share based on access patterns and file activity. Use this report to assign data ownership and support data governance workflows. | +| **Share Audit** | Provides a detailed breakdown of share-level attributes including scan status, last scanned date, file counts, object counts, and active users. Use this report to confirm scan coverage and review the overall state of each share. | + +### Activity + +| Report | Description | +| --- | --- | +| **Activity Investigation** | Displays file system events filtered by date range, user, path, and event type. Use this report to trace the actions of a specific user or investigate changes to a specific file or folder. | + +### Content + +| Report | Description | +| --- | --- | +| **Empty Shares** | Lists shares that contain no files. Use this report to identify shares that can be reviewed for decommissioning or consolidation. | +| **Largest Shares** | Ranks file shares by total size. Use this report to identify shares that consume the most storage and prioritize them for review or cleanup. | +| **Nested Shares** | Identifies shares that are nested inside other shares, creating multiple access paths to the same data with potentially different permissions. Use this report to find and resolve configurations that complicate permission management and access auditing. | +| **Stale Content** | Identifies files and shares that haven't been accessed within a configurable threshold. Use this report to locate data that may be a candidate for archiving, deletion, or access review. | + +### Sensitive Data + +| Report | Description | +| --- | --- | +| **Sensitive Data Activity** | Shows file system events involving files that contain sensitive data, filtered by date range, event type, user, and classification taxonomy. Use this report to identify who is reading, modifying, or deleting sensitive files and to detect potential data exfiltration or misuse. | +| **Sensitive Data Overview** | Provides a high-level summary of sensitive data scan findings across CIFS/SMB file shares, including the number of files with matches, classification terms found, and distribution by host and share. Use this report as a starting point for understanding where sensitive data lives in your file server environment. | +| **Share Audit** | Shows share-level details in the context of sensitive data findings, including which shares contain files with sensitive data matches. Use this report to understand sensitive data distribution across shares and prioritize remediation. | +| **Stale Data** | Identifies files containing sensitive data that haven't been accessed recently. Use this report to find aging sensitive content that may no longer be actively used but still carries exposure risk. | + +## SharePoint Online reports + +For full details on these reports, see [SharePoint Online Reports](/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/reports). + +### Access + +| Report | Description | +| --- | --- | +| **Shared Links Report** | Shows all sharing links across your SharePoint environment, with breakdowns by sharing scope (organization, anonymous, specific people), active status, sensitive data type, and site. Use this report to identify overly broad sharing and links that expose sensitive files. | + +### Content + +| Report | Description | +| --- | --- | +| **ROT Analysis** | Identifies Redundant, Obsolete, and Trivial (ROT) data across your SharePoint sites, including stale files not modified in over a year, duplicate files by content hash, and stale files containing sensitive data. Use this report to prioritize data cleanup and reduce unnecessary exposure of aging content. | +| **Scan Overview** | Summarizes the results of the most recent scan across all sites, including total site count, file count, total storage, and files with sensitive data. Use this report to confirm scan coverage and quickly identify which sites hold the most sensitive content. | diff --git a/docs/accessanalyzer/2601/gettingstarted/_category_.json b/docs/accessanalyzer/2601/gettingstarted/_category_.json new file mode 100644 index 0000000000..3cefeac060 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Quick Start Guides", + "position": 20, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/_category_.json b/docs/accessanalyzer/2601/gettingstarted/active-directory/_category_.json new file mode 100644 index 0000000000..78b3bd0452 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Active Directory", + "position": 20, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/active-directory.md b/docs/accessanalyzer/2601/gettingstarted/active-directory/active-directory.md new file mode 100644 index 0000000000..82de776a1d --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/active-directory.md @@ -0,0 +1,34 @@ +--- +title: "Active Directory Scanning Overview" +description: "Overview of Active Directory scanning capabilities and prerequisites in Access Analyzer" +sidebar_position: 1 +--- + +# Active Directory Scanning Overview + +Access Analyzer scans Active Directory to inventory users, groups, and group memberships across one or more domains. It detects security risks including stale accounts, privileged account exposure, excessive group nesting, and accounts with unusual delegation settings. Findings surface in the AD Scan Summary dashboard, giving security teams a clear picture of their identity posture and the data they need to prioritize remediation. + +## Prerequisites + +Before setting up an Active Directory source group, confirm that your environment meets the requirements below. The source group wizard connects to your domain controllers over LDAP or LDAPS, so the Access Analyzer server must be able to reach them on the network and a domain service account must be available with the appropriate read permissions. + +### Service account + +Access Analyzer uses a domain service account to authenticate against your Active Directory domain controllers and read directory objects. The account must be a member of the domain you're scanning and have read access to the directory tree. + +See [Username and Password](../../configurations/service-accounts/username-password.md) to create the service account and [Active Directory Connector Requirements](../../connectors/activedirectory.md) for the full list of required permissions. + +### Network requirements + +| Port | Protocol | Destination | +| --- | --- | --- | +| 389 | TCP | Domain controllers in the source group (LDAP) | +| 636 | TCP | Domain controllers in the source group (LDAPS, if using SSL) | +| 135–139 | TCP | Domain controllers in the source group (RPC) | +| 49152–65535 | TCP | Domain controllers in the source group (RPC dynamic ports) | + +### Before you begin + +- The fully qualified domain name (FQDN) of each domain controller you plan to add. IP addresses aren't supported — DIGEST-MD5 authentication requires a resolvable hostname and will fail if an IP address is provided. +- A Username and Password service account created in Access Analyzer with Read access to the domain. +- Network connectivity from the Access Analyzer server to port 389 or 636 on each domain controller confirmed. diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/reports.md b/docs/accessanalyzer/2601/gettingstarted/active-directory/reports.md new file mode 100644 index 0000000000..0a091357f8 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/reports.md @@ -0,0 +1,49 @@ +--- +title: "Reports" +description: "Pre-built dashboard available for Active Directory source groups in Access Analyzer" +sidebar_position: 50 +--- + +# Reports + +After the first Active Directory scan completes, the **AD Scan Summary** dashboard becomes available under **Dashboards**. Use the **Domain** filter at the top of the dashboard to focus on a specific domain. + +## AD Scan Summary + +The dashboard is organized into four sections: a summary row at the top, a **Users** section, a **Groups** section, and an **All Risks** section. + +### Summary row + +| Card | Description | +|------|-------------| +| **Domains** | Number of domains scanned in this source group. | +| **Users** | Total number of user objects collected. | +| **Enabled Users** | Number of enabled user accounts. | +| **Groups** | Total number of group objects collected. | +| **Direct Memberships** | Total number of direct group membership relationships. | + +### Users + +| Card | Description | +|------|-------------| +| **Administrator Accounts** | Number of accounts with a non-zero `adminCount` attribute, indicating current or past AdminSDHolder protection. | +| **New Users** | Number of user accounts created in the past 7 days. | +| **Users with Associated Risks** | Number of users who have at least one detected risk. | +| **User Risks** | Table listing each user with associated risks, including the user name, domain, and risk count. | + +### Groups + +| Card | Description | +|------|-------------| +| **Security Groups** | Number of security groups collected. | +| **DLs** | Number of distribution lists (DLs) collected. | +| **Groups with Associated Risks** | Number of groups that have at least one detected risk. | +| **Group Risks** | Table listing each group with associated risks, including the group name, domain, and risk count. | + +### All Risks + +| Card | Description | +|------|-------------| +| **Risks by Level** | Pie chart showing the distribution of detected risks by severity level (High, Medium, Low). | +| **Riskiest Objects** | Table ranking users and groups by the number of associated risks. | +| **Active Directory Risks** | Full table of all detected risks. Columns include risk type, entity name, domain, detection timestamp, risk level, risk category, and risk description. | diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/scanning-options.md b/docs/accessanalyzer/2601/gettingstarted/active-directory/scanning-options.md new file mode 100644 index 0000000000..f940fdae3c --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/scanning-options.md @@ -0,0 +1,11 @@ +--- +title: "Available Scanning Options" +description: "Available scan types for Active Directory source groups" +sidebar_position: 2 +--- + +# Available Scanning Options + +| Scan Option | Description | Available Configurations | +| --- | --- | --- | +| **Active Directory Inventory** | Scans users, groups, and group memberships from all domain controllers in the source group. The first scan runs in full; subsequent scans run differentially, collecting only changes since the last run. | None | diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/schema-reference.md b/docs/accessanalyzer/2601/gettingstarted/active-directory/schema-reference.md new file mode 100644 index 0000000000..7ae58d38c8 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/schema-reference.md @@ -0,0 +1,273 @@ +--- +title: "Active Directory Schema Reference" +sidebar_position: 40 +--- + +# Active Directory Schema Reference + +Access Analyzer stores Active Directory scan data in the `access_analyzer` ClickHouse database. The tables below are created when you set up an Active Directory source group and run a scan. Use this reference when querying scan data directly or integrating Access Analyzer data with external tools. + +:::note +All tables use the `ReplacingMergeTree` engine. Duplicate rows with the same primary key are deduplicated at merge time. Query the `_latest` views to return only the most recent version of each record. +::: + +## Metadata columns + +All tables include the following columns populated by Access Analyzer during each scan: + +| Column | Type | Description | +|--------|------|-------------| +| `scan_id` | `String` | Identifier of the source group that produced this record. | +| `scan_execution_id` | `String` | Identifier of the specific scan run. | +| `scanned_at` | `DateTime` | Timestamp when the record was written. | + +--- + +## Tables + +### Active Directory User + +Stores one row per user object discovered in an Active Directory scan. + +**Primary key:** `object_guid` + +#### Core identity fields + +| Column | Type | Description | +|--------|------|-------------| +| `object_guid` | `UUID` | Globally unique identifier for the user object. | +| `object_sid` | `String` | Security identifier (SID) of the user. | +| `distinguished_name` | `String` | Full distinguished name (DN) of the user in the directory. | +| `canonical_name` | `Nullable(String)` | Optional. Canonical form of the distinguished name. | +| `sam_account_name` | `String` | Pre-Windows 2000 logon name (sAMAccountName). | +| `user_principal_name` | `Nullable(String)` | Optional. User principal name (UPN) in `user@domain` format. | +| `display_name` | `Nullable(String)` | Optional. Display name shown in directory listings. | +| `given_name` | `Nullable(String)` | Optional. First name of the user. | +| `surname` | `Nullable(String)` | Optional. Last name of the user. | +| `enabled` | `Bool` | Whether the user account is enabled. | +| `when_created` | `Nullable(DateTime)` | Optional. Timestamp when the account was created in the directory. | +| `when_changed` | `Nullable(DateTime)` | Optional. Timestamp of the most recent change to the account. | +| `description` | `Nullable(String)` | Optional. Description field set on the user object. | +| `admin_count` | `Nullable(Int32)` | Optional. Value of the `adminCount` attribute; non-zero values indicate the account is or was protected by AdminSDHolder. | +| `primary_group_id` | `Nullable(Int32)` | Optional. Relative identifier (RID) of the user's primary group. | +| `domain_name` | `Nullable(String)` | Optional. NetBIOS or DNS name of the domain. | +| `domain_canonical_name` | `Nullable(String)` | Optional. Canonical (DNS) name of the domain. | +| `cn` | `Nullable(String)` | Optional. Common name (CN) attribute of the user object. | + +#### Contact information + +| Column | Type | Description | +|--------|------|-------------| +| `mail` | `Nullable(String)` | Optional. Email address. | +| `telephone_number` | `Nullable(String)` | Optional. Office telephone number. | +| `mobile` | `Nullable(String)` | Optional. Mobile telephone number. | +| `office` | `Nullable(String)` | Optional. Office location. | +| `street_address` | `Nullable(String)` | Optional. Street address. | +| `city` | `Nullable(String)` | Optional. City. | +| `state` | `Nullable(String)` | Optional. State or province. | +| `postal_code` | `Nullable(String)` | Optional. Postal or ZIP code. | +| `country` | `Nullable(String)` | Optional. Country or region. | + +#### Organizational information + +| Column | Type | Description | +|--------|------|-------------| +| `job_title` | `Nullable(String)` | Optional. Job title. | +| `department` | `Nullable(String)` | Optional. Department. | +| `company` | `Nullable(String)` | Optional. Company or organization name. | +| `manager_dn` | `Nullable(String)` | Optional. Distinguished name of the user's manager. | +| `employee_id` | `Nullable(String)` | Optional. Employee identifier. | + +#### Security information + +| Column | Type | Description | +|--------|------|-------------| +| `user_account_control` | `Nullable(Int32)` | Optional. Bitmask value of the `userAccountControl` attribute controlling account behavior and flags. | +| `password_last_set` | `Nullable(DateTime)` | Optional. Timestamp when the password was last changed. | +| `password_never_expires` | `Nullable(Bool)` | Optional. Whether the password is set to never expire. | +| `account_expires` | `Nullable(String)` | Optional. Expiration date of the account, stored as a string representation of the directory value. | +| `logon_hours` | `Nullable(String)` | Optional. Bitmask string representing the hours during which the user is permitted to log on. | +| `logon_workstations` | `Array(String)` | List of workstations the user is permitted to log on to; empty array indicates no restriction. | +| `smartcard_required` | `Nullable(Bool)` | Optional. Whether the account requires a smart card to log on. | +| `mfa_enforced` | `Nullable(Bool)` | Optional. Whether multi-factor authentication is enforced for this account. | +| `is_deleted` | `Boolean` | Whether the user object has been soft-deleted. Rows where `is_deleted = 1` are excluded from the `active_directory_user_latest` view. | + +#### Activity information + +| Column | Type | Description | +|--------|------|-------------| +| `last_logon` | `Nullable(DateTime)` | Optional. Most recent logon timestamp from the domain controller that serviced the last logon. Not replicated across domain controllers. | +| `last_logon_timestamp` | `Nullable(DateTime)` | Optional. Replicated logon timestamp (`lastLogonTimestamp`); updated at intervals and may lag behind the actual last logon by up to 14 days. | +| `bad_pwd_count` | `Nullable(Int32)` | Optional. Number of consecutive failed logon attempts. | +| `bad_password_time` | `Nullable(DateTime)` | Optional. Timestamp of the last failed logon attempt. | +| `lockout_time` | `Nullable(DateTime)` | Optional. Timestamp when the account was locked out; `NULL` or zero indicates the account isn't locked. | +| `last_logoff` | `Nullable(DateTime)` | Optional. Timestamp of the last logoff. | + +#### Delegation information + +| Column | Type | Description | +|--------|------|-------------| +| `ms_ds_allowed_to_act_on_behalf_of` | `Array(String)` | List of security descriptors for accounts permitted to delegate to this account using resource-based constrained delegation. | +| `ms_ds_allowed_to_delegate_to` | `Array(String)` | List of SPNs this account is permitted to delegate to using constrained delegation. | +| `ms_ds_supported_encryption_types` | `Nullable(Int32)` | Optional. Bitmask of Kerberos encryption types supported by this account. | +| `service_principal_name` | `Array(String)` | List of service principal names (SPNs) registered to this account. | +| `legacy_exchange_dn` | `Nullable(String)` | Optional. Legacy Exchange distinguished name, used for mail routing compatibility. | +| `ms_ds_user_account_control_computer` | `Nullable(Int32)` | Optional. Computer-specific `userAccountControl` flags stored on the user object in hybrid environments. | + +**Relations** + +| Related table | Join column | Description | +|---|---|---| +| `active_directory_group_membership` | `object_sid` via `foreign_sid` | Resolves groups that include this user when the user was added by SID from a foreign domain. | +| `active_directory_group_membership` | `distinguished_name` via `member_dn` | Resolves groups that include this user when the user was added by DN. | +| `active_directory_user_custom_attribute` | `object_guid` | Returns custom attribute values collected for this user. | +| `active_directory_effective_group_membership` | `object_guid` via `member_object_guid` | Returns all groups this user belongs to, including nested memberships. | + +--- + +### Active Directory Group + +Stores one row per group object discovered in an Active Directory scan. + +**Primary key:** `object_guid` + +| Column | Type | Description | +|--------|------|-------------| +| `object_guid` | `UUID` | Globally unique identifier for the group object. | +| `object_sid` | `String` | Security identifier (SID) of the group. | +| `distinguished_name` | `String` | Full distinguished name (DN) of the group in the directory. | +| `sam_account_name` | `Nullable(String)` | Optional. Pre-Windows 2000 name of the group. | +| `name` | `Nullable(String)` | Optional. Display name of the group. | +| `group_scope` | `Nullable(String)` | Optional. Scope of the group: `DomainLocal`, `Global`, or `Universal`. | +| `group_type` | `Nullable(String)` | Optional. Type of the group: `Security` or `Distribution`. | +| `admin_count` | `Nullable(Int32)` | Optional. Value of the `adminCount` attribute; non-zero values indicate the group is or was protected by AdminSDHolder. | +| `primary_group_id` | `Nullable(Int32)` | Optional. Relative identifier (RID) associated with this group when it is used as a primary group. | +| `domain_name` | `Nullable(String)` | Optional. NetBIOS or DNS name of the domain. | +| `domain_canonical_name` | `Nullable(String)` | Optional. Canonical (DNS) name of the domain. | +| `cn` | `Nullable(String)` | Optional. Common name (CN) attribute of the group object. | +| `mail` | `Nullable(String)` | Optional. Email address associated with the group. | +| `is_deleted` | `Boolean` | Whether the group object has been soft-deleted. Rows where `is_deleted = 1` are excluded from the `active_directory_group_latest` view. | + +**Relations** + +| Related table | Join column | Description | +|---|---|---| +| `active_directory_group_membership` | `distinguished_name` via `group_dn` | Lists the direct members of this group. | +| `active_directory_effective_group_membership` | `object_guid` via `group_object_guid` | Lists all effective members of this group, including nested members. | + +--- + +### Active Directory Group Membership + +Stores one row per direct membership relationship between a group and a member object (user or group). Nesting isn't flattened in this table; use `active_directory_effective_group_membership` for flattened membership. + +**Primary key:** `(group_dn, member_dn)` + +| Column | Type | Description | +|--------|------|-------------| +| `group_dn` | `String` | Distinguished name (DN) of the group. | +| `member_dn` | `String` | Distinguished name (DN) of the member object. | +| `foreign_sid` | `Nullable(String)` | Optional. SID of the member when the member is from a foreign (trusted) domain and a DN isn't available. | + +**Relations** + +| Related table | Join column | Description | +|---|---|---| +| `active_directory_group` | `group_dn` = `distinguished_name` | Resolves the group record for this membership row. | +| `active_directory_user` | `member_dn` = `distinguished_name` | Resolves the user record for this membership row when the member is a user. | +| `active_directory_group` | `member_dn` = `distinguished_name` | Resolves the group record for this membership row when the member is a nested group. | +| `active_directory_user` | `foreign_sid` = `object_sid` | Resolves a foreign-domain user by SID when `foreign_sid` is set. | +| `active_directory_group` | `foreign_sid` = `object_sid` | Resolves a foreign-domain group by SID when `foreign_sid` is set. | + +--- + +### Active Directory User Custom Attribute + +Stores custom Active Directory attribute values collected for user objects during a scan. Each row represents one attribute key-value pair for one user. An attribute with no value produces a row with `attr_value = NULL`. + +**Primary key:** `(object_guid, attr_name)` + +| Column | Type | Description | +|--------|------|-------------| +| `object_guid` | `UUID` | Globally unique identifier of the user object. Joins to `active_directory_user.object_guid`. | +| `attr_name` | `String` | LDAP attribute name, as configured in the source group settings. | +| `attr_value` | `Nullable(String)` | Optional. String representation of the attribute value. | + +**Relations** + +| Related table | Join column | Description | +|---|---|---| +| `active_directory_user` | `object_guid` | Returns the full user record for this custom attribute row. | + +--- + +### Active Directory Effective Group Membership + +Stores the fully flattened, transitively resolved group membership graph. This table is populated by the `active_directory_effective_group_membership_mv` materialized view, which refreshes on a schedule after each scan. Each row represents one effective membership relationship at a given nesting depth. + +**Engine:** `MergeTree` (not `ReplacingMergeTree`). The table is rebuilt on each refresh rather than deduplicated by version. + +**Primary key:** `(group_object_guid, member_object_guid)` + +| Column | Type | Description | +|--------|------|-------------| +| `group_object_guid` | `UUID` | Globally unique identifier of the group. Joins to `active_directory_group.object_guid`. | +| `member_object_guid` | `UUID` | Globally unique identifier of the effective member (user or group). Joins to `active_directory_user.object_guid` or `active_directory_group.object_guid`. | +| `nesting_level` | `Int32` | Depth of the membership relationship. A value of `0` indicates direct membership; higher values indicate the number of intermediate groups. | + +**Relations** + +| Related table | Join column | Description | +|---|---|---| +| `active_directory_group` | `group_object_guid` = `object_guid` | Resolves the group name and attributes for this membership row. | +| `active_directory_user` | `member_object_guid` = `object_guid` | Resolves the user record when the effective member is a user. | +| `active_directory_group` | `member_object_guid` = `object_guid` | Resolves the group record when the effective member is a nested group. | + +--- + +## Views + +Access Analyzer creates views that simplify common queries. Use views in preference to querying base tables directly. + +### Deduplication views + +These views apply `FINAL` to the underlying `ReplacingMergeTree` tables to return only the most recent version of each record. Use these as the starting point for any query against Active Directory data. + +| View | Base table | Description | +|------|------------|-------------| +| `active_directory_user_latest` | `active_directory_user` | Returns the most recent version of each user record, deduplicated by `object_guid`, excluding soft-deleted users (`is_deleted = 1`). | +| `active_directory_group_latest` | `active_directory_group` | Returns the most recent version of each group record, deduplicated by `object_guid`, excluding soft-deleted groups (`is_deleted = 1`). | +| `active_directory_group_membership_latest` | `active_directory_group_membership` | Returns the most recent version of each group membership row, deduplicated by `(group_dn, member_dn)`. | +| `active_directory_user_custom_attribute_latest` | `active_directory_user_custom_attribute` | Returns the most recent version of each custom attribute row, deduplicated by `(object_guid, attr_name)`. | + +### Resolution views + +These views resolve raw membership data into UUID-keyed relationships. + +| View | Description | +|------|-------------| +| `active_directory_group_membership_resolved` | Joins `active_directory_group_membership_latest` to the user and group tables to produce a resolved membership graph keyed by `(group_object_guid, member_object_guid)`. Handles both same-domain members (matched by DN) and foreign-domain members (matched by SID). Excludes deleted objects. Used as the source for `active_directory_effective_group_membership_mv`. | + +### Risk views + +These views surface specific account and group hygiene conditions. Each view returns rows in a common shape: `risk_type`, `entity_id`, `entity_name`, `domain`, `detection_timestamp`, and `additional_context`. The `active_directory_risks_summary` view aggregates all risk views into a single result set enriched with catalog metadata. + +| View | Description | +|------|-------------| +| `active_directory_empty_groups` | Groups that have no effective members. | +| `active_directory_single_member_groups` | Groups that have exactly one effective member. | +| `active_directory_large_groups` | Groups that have more than 500 effective members. | +| `active_directory_duplicate_groups_mv` | Groups whose effective membership set is identical to that of at least one other group. | +| `active_directory_circular_nesting_mv` | Groups involved in circular nesting or with a nesting depth of 10 or more. | +| `active_directory_stale_users` | Enabled user accounts with no logon activity in the past 90 to 365 days. | +| `active_directory_very_stale_users` | Enabled user accounts with no logon activity for more than 365 days. | +| `active_directory_isolated_users` | Enabled user accounts that belong to no groups. | +| `active_directory_no_logon_users` | Enabled user accounts with no recorded logon timestamp. | +| `active_directory_password_never_expires` | Enabled user accounts configured with a non-expiring password. | +| `active_directory_password_not_required` | Enabled user accounts where the `PASSWD_NOTREQD` flag is set in `user_account_control`. | +| `active_directory_old_passwords` | Enabled user accounts whose password has not changed in more than 90 days. | +| `active_directory_dc_logon_rights` | Enabled users who are effective members of privileged groups that grant domain controller logon rights (for example, Domain Admins, Enterprise Admins). | +| `active_directory_risks_summary_mv` | Union of all individual risk views. Returns one row per detected risk. | +| `active_directory_risks_summary` | Enriches `active_directory_risks_summary_mv` with risk level, category, and description from the `active_directory_risk_catalog` reference table. Use this view to query all risks with their human-readable metadata. | +| `active_directory_risks_by_domain` | Aggregates risk counts by domain and risk type, sourced from `active_directory_risks_summary_mv`. | +| `active_directory_group_member_counts` | Returns the total effective member count for each group. Intermediate view used by the group risk views. | diff --git a/docs/accessanalyzer/2601/gettingstarted/active-directory/set-up-source-group.md b/docs/accessanalyzer/2601/gettingstarted/active-directory/set-up-source-group.md new file mode 100644 index 0000000000..83c7483472 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/active-directory/set-up-source-group.md @@ -0,0 +1,41 @@ +--- +title: "Set Up Active Directory Source Group" +description: "Configure an Active Directory source group in Access Analyzer" +sidebar_position: 3 +--- + +# Set Up Active Directory Source Group + +1. Navigate to **Configuration** > **Source Groups** and click **Add Source**. The source group wizard opens. +2. Select **Active Directory** and click **Next**. +3. Enter a **Source Group Name**. +4. Select a service account from the **Service Account** dropdown, or click **+** to create one inline. Service accounts store the credentials Access Analyzer uses to connect to your domain controllers. See [Service Accounts](../../configurations/service-accounts/overview.md) for details. +5. Click **Add** under **Domain Controllers**, then select **Add Manually**. +6. Enter the following for each domain controller: + - **Server Name / IP** — The FQDN of the domain controller (for example, `dc01.corp.example.com`). IP addresses aren't supported. To add multiple domain controllers, separate entries with a comma or press **Enter** after each one. + - **Domain** — The DNS domain name (for example, `corp.example.com`). Applied to all entries above. + - **Port** — The LDAP port. Default is `389`. Use `636` for LDAPS. +7. Click **Add domain controller**, then click **Done**. Repeat steps 5–7 for each additional domain. +8. If your domain controllers use self-signed certificates on port 636, select **Ignore SSL errors**. +9. Click **Test Connection** to verify connectivity. Each domain controller displays a **Connected** or **Failed** status. Resolve any failures before proceeding. +10. Click **Next**. +11. Under **Scanner Location**, select **System scanner** to run scans from the Access Analyzer service, or select **Custom scanner** to use a deployed scanner. See [Scanners](../../configurations/source-groups/scanners/overview.md) for details. +12. Under **Scan Schedule**, select when to run the scan: + - **Now** — Starts the scan immediately after setup completes. + - **At** — Runs the scan once at a specific date and time. + - **Advanced** — Runs the scan on a recurring schedule defined by a cron expression. +13. Click **Complete Setup**. + +## What happens next + +Access Analyzer creates the source group and a scan for each domain controller you added. If you selected **Now**, the Active Directory Inventory scan starts immediately. + +To check scan progress, navigate to **Configuration** > **Scan Executions**. + +## Edit a source group + +To modify an existing Active Directory source group, navigate to **Configuration** > **Source Groups**, select the source group, and click **Edit**. The wizard reopens with your current configuration pre-populated. You can update the source group name, service account, domain controllers, and scan schedule. + +:::note +Updating the service account affects all domain controllers in the source group, as they share a single set of credentials. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/_category_.json b/docs/accessanalyzer/2601/gettingstarted/entra-id/_category_.json new file mode 100644 index 0000000000..03206793dc --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Entra ID", + "position": 40, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/entra-id.md b/docs/accessanalyzer/2601/gettingstarted/entra-id/entra-id.md new file mode 100644 index 0000000000..07dd999590 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/entra-id.md @@ -0,0 +1,38 @@ +--- +title: "Entra ID Scanning Overview" +description: "Overview of Entra ID scanning capabilities and prerequisites in Access Analyzer" +sidebar_position: 1 +--- + +# Entra ID Scanning Overview + +Access Analyzer connects to Microsoft Entra ID to synchronize users, groups, role assignments, and Microsoft Information Protection (MIP) sensitivity labels from your tenant. MIP labels — defined in Microsoft Purview — are retrieved during the scan and made available in the Sensitive Data configuration, where you can map them to sensitive data types for use in file server and SharePoint Online scans. + +:::note +MIP sensitivity labels are collected during the Entra ID sync and become available for use in **File Server** and **SharePoint Online** Sensitive Data scans. Run the Entra ID scan at least once before enabling MIP label detection in those source groups. +::: + +## Prerequisites + +Before setting up an Entra ID source group, confirm that your environment meets the requirements below. The source group wizard connects to Microsoft Entra ID over HTTPS using a registered application's client credentials, so the Access Analyzer server must be able to reach the Microsoft identity platform and an app registration must be configured in your tenant with the required API permissions. + +### Service account + +Access Analyzer uses a Client ID and Secret service account to authenticate with Microsoft Entra ID via the Microsoft Graph API. This requires a registered application in your Entra ID tenant with the appropriate API permissions granted and a client secret generated for that application. + +See [Client ID/Secret service account](../../configurations/service-accounts/client-id-secret.md) to create the service account and [Entra ID](../../connectors/entra-id/overview.md) for instructions on registering the application and granting the required permissions. + +### Network requirements + +| Protocol | Port | Destination | +| --- | --- | --- | +| HTTPS | 443 | Microsoft identity platform (`login.microsoftonline.com`) | +| HTTPS | 443 | Microsoft Graph API (`graph.microsoft.com`) | + +### Before you begin + +- A registered application in your Entra ID tenant with the required API permissions granted, including `InformationProtectionPolicy.Read.All` for MIP label retrieval. +- The application's **Tenant ID** and **Client ID**. +- A client secret generated for the application. +- A Client ID and Secret service account created in Access Analyzer. +- Network connectivity from the Access Analyzer server to port 443 confirmed. diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/reports.md b/docs/accessanalyzer/2601/gettingstarted/entra-id/reports.md new file mode 100644 index 0000000000..26cfa83f41 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/reports.md @@ -0,0 +1,42 @@ +--- +title: "Reports" +description: "Pre-built dashboard available for Entra ID source groups in Access Analyzer" +sidebar_position: 50 +--- + +# Reports + +After the first Entra ID scan completes, the **Entra ID Scan Summary** dashboard becomes available under **Dashboards**. Use the **Tenant** filter at the top of the dashboard to focus on a specific Entra ID tenant. + +## Entra ID Scan Summary + +The dashboard is organized into three sections: a summary row at the top, an **Identities** section, and a **MIP Labels** section. + +### Summary row + +| Card | Description | +|------|-------------| +| **Users** | Total number of user objects synced from the tenant. | +| **Groups** | Total number of group objects synced from the tenant. | +| **Roles** | Total number of Azure AD role definitions retrieved. | +| **MIP Labels** | Total number of Microsoft Information Protection sensitivity labels retrieved from the tenant. | + +### Identities + +| Card | Description | +|------|-------------| +| **Guest Users** | Number of user accounts with `userType = Guest`. | +| **MFA Configured** | Number of users with multi-factor authentication configured. | +| **Group Memberships** | Total number of direct group membership records. | +| **Role Assignments** | Total number of role assignment records (user or group assigned to a role). | + +### MIP Labels + +| Card | Description | +|------|-------------| +| **Active Labels** | Number of sensitivity labels currently active in the tenant. | +| **Label List** | Table listing all retrieved labels, including label name, classification level, and whether the label is active. | + +:::note +MIP labels retrieved here are made available in **Configuration** > **Sensitive Data**, where you can map them to sensitive data types for use in File Server and SharePoint Online scans. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/scanning-options.md b/docs/accessanalyzer/2601/gettingstarted/entra-id/scanning-options.md new file mode 100644 index 0000000000..7de69e0ccf --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/scanning-options.md @@ -0,0 +1,17 @@ +--- +title: "Scanning options" +description: "Available scan types for Entra ID source groups" +sidebar_position: 2 +--- + +# Scanning options + +| Scan type | Description | +| --- | --- | +| **Users, Groups, and Roles** | Synchronizes users, groups, and role assignments from the Entra ID tenant. The first scan runs in full; subsequent scans collect only changes since the last run. MIP sensitivity labels are retrieved automatically as part of every scan. | + +## MIP label retrieval + +When an Entra ID source group runs, Access Analyzer automatically retrieves Microsoft Information Protection (MIP) sensitivity labels defined in the tenant. These labels are made available in the **Configuration** > **Sensitive Data** page, where you can map them to sensitive data types for use in file server and SharePoint Online scans. + +There are no per-source-group configuration options for MIP label retrieval — it runs automatically as part of every scan. To configure how labels are applied to files, see [Sensitive Data Configuration](../../configurations/sensitive-data.md). diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/schema-reference.md b/docs/accessanalyzer/2601/gettingstarted/entra-id/schema-reference.md new file mode 100644 index 0000000000..42a6788f1c --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/schema-reference.md @@ -0,0 +1,122 @@ +--- +title: "Schema reference" +sidebar_position: 40 +--- + +# Entra ID schema reference + +Access Analyzer stores Entra ID scan data in the `access_analyzer` ClickHouse database. The tables below are populated when you set up an Entra ID source group and run a scan. Use this reference when querying scan data directly or integrating Access Analyzer data with external tools. + +Entra ID data is stored in shared tables that serve multiple connector types. Each row is scoped to your tenant using the `tenancyReference` column, which corresponds to your Entra ID tenant. + +:::note +All tables use the `ReplacingMergeTree` engine. Duplicate rows with the same primary key are deduplicated at merge time. Use the `FINAL` keyword or query the available `_latest` views to return only the most recent version of each record. +::: + +## Metadata columns + +All tables include the following columns populated by Access Analyzer during each scan: + +| Column | Type | Description | +|--------|------|-------------| +| `tenancyReference` | `UUID` | Identifier of the Entra ID tenant that produced this record. | +| `connectorReference` | `UUID` | Identifier of the connector job run. | +| `fullCrawlTimestampUtc` | `DateTime64(6)` | Timestamp of the most recent full sync for this tenant. | +| `crawlTimestampUtc` | `DateTime64(6)` | Timestamp when this record was written. Used as the version column for deduplication. | + +--- + +## Tables + +### principals + +Stores users, groups, and roles synced from the Entra ID tenant. Each row represents one identity object. + +**Primary key:** `entityId` + +#### Core identity fields + +| Column | Type | Description | +|--------|------|-------------| +| `entityId` | `UUID` | Unique identifier for this identity object within Access Analyzer. | +| `sourceSystemId` | `String` | Object ID from Entra ID (the Azure AD `objectId`). | +| `name` | `String` | Internal name of the object. | +| `displayName` | `String` | Display name as it appears in Entra ID. | +| `emailAddress` | `Nullable(String)` | Optional. Primary email address. | +| `firstName` | `Nullable(String)` | Optional. Given name (users only). | +| `lastName` | `Nullable(String)` | Optional. Surname (users only). | +| `isDeleted` | `Bool` | Whether the object has been soft-deleted. | +| `deletedDate` | `Nullable(DateTime64(6))` | Optional. Timestamp when the object was deleted. | +| `lastModified` | `Nullable(DateTime64(6))` | Optional. Timestamp of the most recent change. | +| `lastActive` | `Nullable(DateTime64(6))` | Optional. Timestamp of the most recent sign-in activity. | + +#### User-specific fields + +| Column | Type | Description | +|--------|------|-------------| +| `azureAdUserPrincipalName` | `Nullable(String)` | Optional. User principal name (UPN) in `user@domain` format. | +| `azureAdUserType` | `Nullable(String)` | Optional. Type of user account: `Member` or `Guest`. | +| `azureAdMfaConfigured` | `Nullable(Bool)` | Optional. Whether MFA is configured for the user. | +| `disabled` | `Nullable(Bool)` | Optional. Whether the user account is disabled. | +| `department` | `Nullable(String)` | Optional. Department attribute from Entra ID. | +| `jobTitle` | `Nullable(String)` | Optional. Job title attribute from Entra ID. | +| `lastDirSyncTime` | `Nullable(DateTime64(6))` | Optional. Last directory sync timestamp for hybrid-joined accounts. | + +#### Group-specific fields + +| Column | Type | Description | +|--------|------|-------------| +| `azureAdGroupType` | `Nullable(String)` | Optional. Group type: `Security`, `Distribution`, or `M365`. | +| `isSecurityEnabled` | `Nullable(Bool)` | Optional. Whether the group is security-enabled. | +| `isMailEnabled` | `Nullable(Bool)` | Optional. Whether the group is mail-enabled. | +| `memberCount` | `Nullable(Int32)` | Optional. Number of direct members. | +| `dynamicMembershipEnabled` | `Nullable(Bool)` | Optional. Whether the group uses dynamic membership rules. | + +#### Role-specific fields + +| Column | Type | Description | +|--------|------|-------------| +| `azureRoleTemplateId` | `Nullable(String)` | Optional. Stable template ID for built-in roles (consistent across tenants). | +| `azureRoleAllowedPrincipalTypes` | `Nullable(String)` | Optional. Principal types that can be assigned to this role. | + +--- + +### memberships + +Stores group membership records — both direct and nested. Each row represents one membership relationship. + +**Primary key:** `(groupId, memberId, role)` + +| Column | Type | Description | +|--------|------|-------------| +| `groupId` | `UUID` | `entityId` of the group. Joins to `principals.entityId`. | +| `memberId` | `UUID` | `entityId` of the member (user, group, or service principal). Joins to `principals.entityId`. | +| `membershipSource` | `String` | How the membership was established: `Direct`, `Nested`, or `Dynamic`. | +| `role` | `String` | Role of the member within the group: `Owner`, `Member`, or `Guest`. | +| `expandedFromGroupId` | `Nullable(UUID)` | Optional. For nested memberships, the intermediate group through which this membership was resolved. | +| `isDeleted` | `Bool` | Whether this membership record has been removed. | + +--- + +### sensitivity_labels + +Stores Microsoft Information Protection (MIP) sensitivity labels retrieved from the tenant during an Entra ID scan. + +**Primary key:** `sensitivitylabelId` + +| Column | Type | Description | +|--------|------|-------------| +| `sensitivitylabelId` | `UUID` | Unique identifier for this label within Access Analyzer. | +| `name` | `String` | Internal name of the label. | +| `displayName` | `String` | Display name shown to users in Microsoft 365 applications. | +| `description` | `Nullable(String)` | Optional. Description of the label's purpose. | +| `isActive` | `Bool` | Whether the label is currently active in the tenant. | +| `isDeleted` | `Bool` | Whether the label has been deleted. | +| `classificationLevel` | `Nullable(String)` | Optional. Classification level assigned to the label. | +| `priority` | `Int32` | Display order priority. Lower values appear first. | +| `parentLabelId` | `Nullable(UUID)` | Optional. For sublabels, the `sensitivitylabelId` of the parent label. | +| `labelId` | `Nullable(String)` | Microsoft GUID for the label as defined in Microsoft Purview. | + +:::note +Labels stored here are the source data for MIP label mapping in **Configuration** > **Sensitive Data**. After mapping labels to sensitive data types, they are available for detection during File Server and SharePoint Online scans. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/entra-id/set-up-source-group.md b/docs/accessanalyzer/2601/gettingstarted/entra-id/set-up-source-group.md new file mode 100644 index 0000000000..108570ef48 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/entra-id/set-up-source-group.md @@ -0,0 +1,43 @@ +--- +title: "Set up an Entra ID source group" +description: "Configure an Entra ID source group in Access Analyzer" +sidebar_position: 3 +--- + +# Set up an Entra ID source group + +1. Navigate to **Configuration** > **Source Groups** and click **Add Source**. The source group wizard opens. + +2. Select **Entra ID** and click **Next**. + +3. Enter a **Source Group Name**. + +4. Select a service account from the **Service Account** dropdown, or click **+** to create one inline. Entra ID requires a **Client ID and Secret** service account type. See [Service Accounts](../../configurations/service-accounts/overview.md) for details. + +5. Enter the **Tenant ID** for your Entra ID directory. This must be a valid UUID (for example, `550e8400-e29b-41d4-a716-446655440000`). + +6. Click **Test Connection** to verify that Access Analyzer can authenticate to your Entra ID tenant. Resolve any failures before proceeding. + +7. Click **Next**. + +8. Under **Scan Schedule**, select when to run the scan: + + - **Now** — Starts the scan immediately after setup completes. + - **At** — Runs the scan once at a specific date and time. + - **Advanced** — Runs the scan on a recurring schedule defined by a cron expression. + +9. Click **Complete Setup**. + +## What happens next + +Access Analyzer creates the source group and begins syncing users, groups, and roles from your Entra ID tenant. If you selected **Now**, the scan starts immediately. MIP sensitivity labels are retrieved automatically as part of the scan. + +To check scan progress, navigate to **Configuration** > **Scan Executions**. + +## Edit a source group + +To modify an existing Entra ID source group, navigate to **Configuration** > **Source Groups**, select the source group, and click **Edit**. The wizard reopens with your current configuration pre-populated. You can update the source group name, service account, tenant ID, and scan schedule. + +:::note +Updating the service account replaces the client credentials used to authenticate with Entra ID. Ensure the new service account has the required API permissions before saving. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/_category_.json b/docs/accessanalyzer/2601/gettingstarted/file-servers/_category_.json new file mode 100644 index 0000000000..dbe2c40136 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "File Servers", + "position": 30, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/file-servers.md b/docs/accessanalyzer/2601/gettingstarted/file-servers/file-servers.md new file mode 100644 index 0000000000..a0640d0062 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/file-servers.md @@ -0,0 +1,50 @@ +--- +title: "File Server Scanning Overview" +description: "Overview of file server scanning capabilities and prerequisites in Access Analyzer" +sidebar_position: 1 +--- + +# File Server Scanning Overview + +Access Analyzer scans file servers over SMB to map share permissions, folder-level ACLs, and file ownership across your environment. It can also scan file contents to locate sensitive data and, if activity monitoring is configured, track file access events over time. Reports surface open access, broken inheritance, direct user permissions, and sensitive data exposure — giving security and compliance teams the visibility they need to reduce unnecessary access and meet data protection requirements. + +## Supported platforms + +Access Analyzer scans any SMB-compatible file server. For platform-specific requirements, see the connector page for your environment: + +- [CIFS / SMB File Share](../../connectors/file-servers/cifs.md) — Windows file servers and Samba +- [NetApp ONTAP](../../connectors/file-servers/netapp.md) +- [Dell Isilon / PowerScale](../../connectors/file-servers/isilon-powerscale.md) +- [Dell Unity](../../connectors/file-servers/dell-unity.md) +- [Dell EMC VNX](../../connectors/file-servers/vnx.md) +- [Dell EMC Celerra](../../connectors/file-servers/celerra.md) + +## Prerequisites + +Before setting up a file server source group, confirm that your environment meets the requirements below. The source group wizard connects to your file servers over SMB, so the Access Analyzer server must be able to reach them on the network and a service account must be available with read access to the shares you want to scan. + +### Service account + +Access Analyzer uses a service account with a username and password to authenticate against your file servers over SMB and enumerate shares, permissions, and file contents. The account needs read access to the shares and permission to read object security descriptors. + +See [Username and Password](../../configurations/service-accounts/username-password.md) to create the service account and [CIFS / SMB File Share](../../connectors/file-servers/cifs.md) for the full permission requirements. + +### Network requirements + +| Port | Protocol | Destination | +|------|----------|-------------| +| 445 | TCP | File servers in the source group | + +### Before you begin + +- The hostname or IP address of each file server you plan to add. +- A Username and Password service account created in Access Analyzer with read access to the target file servers. +- Network connectivity from the Access Analyzer server to port 445 on each file server confirmed. + +:::note +When you add a file server source group, Access Analyzer automatically creates a **Local Users and Groups** scan for each host. This scan collects local user and group accounts directly from the file server and runs alongside your Access and Sensitive Data scans. +::: + +:::note +File activity reports — including open, modify, and delete events, and anomaly detection — require a separate **Netwrix Activity Monitor** deployment. Without Activity Monitor, activity-related reports will show no data. See [File Activity Monitoring](../../overview/overview.md#key-capabilities) for details. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/reports.md b/docs/accessanalyzer/2601/gettingstarted/file-servers/reports.md new file mode 100644 index 0000000000..1fe8e943ad --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/reports.md @@ -0,0 +1,35 @@ +--- +title: "Reports" +description: "Pre-built reports available for File Servers source groups in Access Analyzer" +sidebar_position: 50 +--- + +# Reports + +File Servers source groups include a set of pre-built reports that answer common security questions about permissions, sensitive data exposure, access patterns, and data content across your CIFS/SMB file shares. Reports are available under the Reports section after the first scan completes and update each time a scan runs. + +:::note +Activity reports (Activity Investigation and Sensitive Data Activity) require Netwrix Activity Monitor (NAM) to be configured and streaming events to Access Analyzer. See [Activity Monitor Integration](../../configurations/activity-monitor-integration.md) for setup instructions. +::: + +## Available reports + +| Location | Report | Description | +|----------|--------|-------------| +| Access / Broken Inheritance | Broken Inheritance | Lists shares and folders where permission inheritance has been broken, meaning the folder's ACL no longer follows its parent. Use this report to find locations where custom permission assignments may have introduced inconsistencies or unexpected access. | +| Access / Domain User ACLs | Domain User ACLs | Shows share and folder permissions assigned directly to domain user accounts. Use this report to identify accounts with direct ACL entries that should be managed through groups instead. | +| Access / High Risk ACLs | High Risk ACLs | Identifies folders where broad trustees such as Everyone, Authenticated Users, or Domain Users appear in the access control list. Use this report to locate and remediate over-permissioned folders that expose data to wide audiences. | +| Access / Local Administrators | Local Administrators | Lists local administrator accounts and the hosts where they hold that privilege. Use this report to identify non-standard or unauthorized local administrator assignments across your file servers. | +| Access / Missing Full Control | Missing Full Control | Lists folders where no trustee holds Full Control permission. Use this report to identify folders that may lack a clear owner or administrator and address potential access management gaps. | +| Access / Open Access | Open Access | Identifies folders and shares accessible to broad groups or where sensitive data is reachable without restriction. Use this report to prioritize remediation of the most exposed locations in your file server environment. | +| Access / Probable Owner | Probable Owner | Identifies the most likely owner for each share based on access patterns and file activity. Use this report to assign data ownership and support data governance workflows. | +| Access / Share Audit | Share Audit | Provides a detailed breakdown of share-level attributes including scan status, last scanned date, file counts, object counts, and active users. Use this report to confirm scan coverage and review the overall state of each share. | +| Activity / Activity Investigation | Activity Investigation | Displays file system events filtered by date range, user, path, and event type. Use this report to trace the actions of a specific user or investigate changes to a specific file or folder. | +| Content / Empty Shares | Empty Shares | Lists shares that contain no files. Use this report to identify shares that can be reviewed for decommissioning or consolidation. | +| Content / Largest Shares | Largest Shares | Ranks file shares by total size. Use this report to identify shares that consume the most storage and prioritize them for review or cleanup. | +| Content / Nested Shares | Nested Shares | Identifies shares that are nested inside other shares, creating multiple access paths to the same data with potentially different permissions. Use this report to find and resolve configurations that complicate permission management and access auditing. | +| Content / Stale Content | Stale Content | Identifies files and shares that haven't been accessed within a configurable threshold. Use this report to locate data that may be a candidate for archiving, deletion, or access review. | +| Sensitive Data / Sensitive Data Activity | Sensitive Data Activity | Shows file system events involving files that contain sensitive data, filtered by date range, event type, user, and classification taxonomy. Use this report to identify who is reading, modifying, or deleting sensitive files and to detect potential data exfiltration or misuse. | +| Sensitive Data / Sensitive Data Overview | Sensitive Data Overview | Provides a high-level summary of sensitive data scan findings across CIFS/SMB file shares, including the number of files with matches, classification terms found, and distribution by host and share. Use this report as a starting point for understanding where sensitive data lives in your file server environment. | +| Sensitive Data / Share Audit | Share Audit | Shows share-level details in the context of sensitive data findings, including which shares contain files with sensitive data matches. Use this report to understand sensitive data distribution across shares and prioritize remediation. | +| Sensitive Data / Stale Data | Stale Data | Identifies files containing sensitive data that haven't been accessed recently. Use this report to find aging sensitive content that may no longer be actively used but still carries exposure risk. | diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/scanning-options.md b/docs/accessanalyzer/2601/gettingstarted/file-servers/scanning-options.md new file mode 100644 index 0000000000..bd3c282d20 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/scanning-options.md @@ -0,0 +1,29 @@ +--- +title: "Available Scanning Options" +description: "Available scan types and configuration options for file server source groups" +sidebar_position: 2 +--- + +# Available Scanning Options + +| Scan Option | Description | Available Configurations | +| --- | --- | --- | +| **Access** | Scans file server permissions and access controls to identify who has access to what. | Share selection (all shares or custom), file-level permissions, concurrent workers (1–20), scan depth | +| **Sensitive Data** | Scans file contents for sensitive data patterns such as personally identifiable information (PII), credentials, protected health information (PHI), and financial records. The first scan runs in full; subsequent scans run differentially, collecting only changes since the last run. | Share selection (all shares or custom), sensitive data types, optical character recognition (OCR), differential scan | + +## Scan Configuration + +**Access** + +- **Include Shares** — Select **All shares** to scan every share on the server, or **Custom selection** to specify which shares to include. +- **Exclude Shares** — Enter share paths to skip. Wildcards are supported (for example, `\\fileserver\*\temp*`). +- **Hidden shares** — Select **Automatically enumerate hidden shares** to include hidden shares. Use **Exclude Hidden Shares** to skip specific ones (for example, `ADMIN$, C$, IPC$`). +- **File-level permissions** — Select **Include file-level permission data** to collect permissions at the individual file level in addition to folder level. This increases scan time. +- **Workers** — Sets the number of concurrent enumeration threads. Default is `3`; valid range is `1–20`. Increase to improve scan speed; decrease to reduce load on the file server. +- **Scan Depth** — Sets the maximum number of directory levels the scan traverses. Default is `50`. Reduce this value to limit scanning to the top levels of a directory tree. + +**Sensitive Data** + +- **Include/Exclude Shares** — Same share selection options as the Access scan. +- **Sensitive data types** — Select **Inherit from Global Settings** to use the system-wide classification configuration, or disable this option to configure types for this source group. Enable each type you want to detect and assign a classification label. +- **OCR** — Select **Run OCR** to scan images, screenshots, and scanned documents for sensitive text using optical character recognition. This increases processing time. diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/schema-reference.md b/docs/accessanalyzer/2601/gettingstarted/file-servers/schema-reference.md new file mode 100644 index 0000000000..0c380f6b62 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/schema-reference.md @@ -0,0 +1,201 @@ +--- +title: "File Servers Schema Reference" +sidebar_position: 40 +--- + +# File Servers Schema Reference + +Access Analyzer stores File Server scan data in the `access_analyzer` ClickHouse database. The tables below are created when you set up a File Server source group and run a scan. Use this reference when querying scan data directly or integrating Access Analyzer data with external tools. + +:::note +All tables use the `ReplacingMergeTree` engine. Duplicate rows with the same primary key are deduplicated at merge time. Query the `_latest` views to return only the most recent version of each record. +::: + +## Metadata columns + +All tables include the following columns populated by Access Analyzer during each scan: + +| Column | Type | Description | +|--------|------|-------------| +| `scan_id` | `String` | Identifier of the source group that produced this record. | +| `scan_execution_id` | `String` | Identifier of the specific scan run. | +| `scanned_at` | `DateTime` | Timestamp when the record was written. | + +--- + +## Tables + +### CIFS Object + +Stores the file system inventory collected during a scan — one row per file, directory, or share discovered on a file server. + +| Column | Type | Description | +|--------|------|-------------| +| `host` | `String` | Hostname of the file server. | +| `share_name` | `String` | Name of the share on the file server. | +| `share_path` | `String` | Universal Naming Convention (UNC) path of the share root. | +| `path` | `String` | Full path of the object within the share. | +| `object_type` | `Enum8('FILE', 'DIRECTORY', 'SHARE')` | Whether the object is a file, directory, or share. | +| `parent_path` | `String` | Full path of the parent directory. | +| `name` | `String` | Name of the file or directory. | +| `file_extension` | `String` | File extension, if applicable. Empty string for directories and shares. | +| `file_size` | `UInt64` | Size of the file in bytes. Zero for directories and shares. | +| `owner_sid` | `String` | Security identifier (SID) of the file or directory owner. | +| `group_owner_sid` | `String` | SID of the primary group owner. | +| `created_time` | `Nullable(DateTime)` | Optional. Timestamp when the object was created. | +| `modified_time` | `Nullable(DateTime)` | Optional. Timestamp when the object was last modified. | +| `accessed_time` | `Nullable(DateTime)` | Optional. Timestamp when the object was last accessed. | +| `scan_status` | `Enum8('SUCCESS', 'ERROR')` | Whether the object was scanned successfully. | +| `error_message` | `String` | Error detail if `scan_status` is `ERROR`. Empty string on success. | +| `attributes` | `Array(Enum8('DIRECTORY', 'READONLY', 'HIDDEN', 'SYSTEM', 'ARCHIVE', 'COMPRESSED', 'ENCRYPTED'))` | Windows file attributes applied to the object. | +| `inheritance_flags` | `UInt16` | Bitmask representing ACL inheritance settings on the object. | +| `is_protected` | `Nullable(Bool)` | Optional. Whether the object's ACL is protected from inheritance. | +| `is_world_readable` | `Nullable(Bool)` | Optional. Whether any well-known open SID (for example, Everyone) has read access. | +| `is_world_writable` | `Nullable(Bool)` | Optional. Whether any well-known open SID has write access. | +| `is_admin_only` | `Nullable(Bool)` | Optional. Whether access is restricted to administrative accounts only. | +| `has_explicit_deny` | `Nullable(Bool)` | Optional. Whether the object has at least one explicit deny ACE. | +| `permission_count` | `UInt16` | Total number of ACEs on the object. | +| `unique_trustees_count` | `UInt16` | Number of distinct trustees with permissions on the object. | +| `permission_flags` | `UInt16` | Bitmask summarizing the permission state of the object. | +| `is_complete` | `Bool` | Whether the scan fully enumerated this object's permissions before the scan completed. | +| `hard_delete` | `Bool` | Internal flag used by `ReplacingMergeTree` to exclude deleted rows. Rows where `hard_delete = 1` are suppressed at query time when querying with `FINAL`. | + +**Relations** + +| Related table | Join column | Description | +|---------------|-------------|-------------| +| `cifs_permission` | `host`, `share_name`, `path` | Resolves NTFS permissions assigned to this file or directory. | +| `cifs_sensitive_data` | `host`, `share_name`, `path` | Resolves sensitive data findings for this file. | + +--- + +### CIFS Permission + +Stores NTFS ACEs (access control entries) for files and directories — one row per trustee per path. + +| Column | Type | Description | +|--------|------|-------------| +| `trustee_sid` | `String` | SID of the user or group that this ACE grants or denies access to. | +| `host` | `String` | Hostname of the file server. | +| `share_name` | `String` | Name of the share containing the object. | +| `path` | `String` | Full path of the object this ACE applies to. | +| `permissions` | `Array(Enum8('FILE_READ_DATA', 'FILE_WRITE_DATA', 'FILE_APPEND_DATA', 'FILE_READ_EA', 'FILE_WRITE_EA', 'FILE_EXECUTE', 'FILE_DELETE_CHILD', 'FILE_READ_ATTRIBUTES', 'FILE_WRITE_ATTRIBUTES', 'DIR_LIST', 'DIR_ADD_FILE', 'DIR_ADD_SUB_DIR', 'DIR_DELETE_CHILD', 'DELETE', 'READ_CONTROL', 'WRITE_DAC', 'WRITE_OWNER', 'GENERIC_ALL', 'GENERIC_EXECUTE', 'GENERIC_WRITE', 'GENERIC_READ'))` | Individual permission flags included in this ACE. | +| `normalized_permissions` | `FixedString(6)` | Six-character string encoding the effective permissions (for example, `RWXDMC`) for use in summary queries. | +| `access_type` | `Enum8('ALLOW', 'DENY')` | Whether this ACE allows or denies access. | +| `access_mask` | `UInt32` | Raw Windows access mask bitmask for this ACE. | +| `inheritance_flags` | `UInt16` | Bitmask describing how this ACE propagates to child objects. | +| `is_inherited` | `Bool` | Whether this ACE was inherited from a parent object rather than set explicitly. | +| `mip_label_id` | `Nullable(String)` | Optional. Microsoft GUID of the MIP sensitivity label applied to this object. | +| `mip_label_name` | `Nullable(String)` | Optional. Display name of the MIP sensitivity label applied to this object. | +| `hard_delete` | `Bool` | Internal flag used by `ReplacingMergeTree` to exclude deleted rows. | + +**Relations** + +| Related table | Join column | Description | +|---------------|-------------|-------------| +| `cifs_object` | `host`, `share_name`, `path` | Resolves file system object details for this ACE. | +| `cifs_share_permission` | `host`, `share_name` | Resolves the share-level permissions that apply in combination with this NTFS ACE. | + +--- + +### CIFS Share Permission + +Stores share-level ACEs — one row per trustee per share. Share permissions apply in addition to NTFS permissions; the effective access a user has is the intersection of both. + +| Column | Type | Description | +|--------|------|-------------| +| `trustee_sid` | `String` | SID of the user or group that this share ACE grants or denies access to. | +| `host` | `String` | Hostname of the file server. | +| `share_name` | `String` | Name of the share this ACE applies to. | +| `permissions` | `Array(Enum8('FILE_READ_DATA', 'FILE_WRITE_DATA', 'FILE_APPEND_DATA', 'FILE_READ_EA', 'FILE_WRITE_EA', 'FILE_EXECUTE', 'FILE_DELETE_CHILD', 'FILE_READ_ATTRIBUTES', 'FILE_WRITE_ATTRIBUTES', 'DIR_LIST', 'DIR_ADD_FILE', 'DIR_ADD_SUB_DIR', 'DIR_DELETE_CHILD', 'DELETE', 'READ_CONTROL', 'WRITE_DAC', 'WRITE_OWNER', 'GENERIC_ALL', 'GENERIC_EXECUTE', 'GENERIC_WRITE', 'GENERIC_READ'))` | Individual permission flags included in this share ACE. | +| `normalized_permissions` | `FixedString(6)` | Six-character string encoding the effective permissions for use in summary queries. | +| `access_type` | `Enum8('ALLOW', 'DENY')` | Whether this ACE allows or denies access at the share level. | +| `access_mask` | `UInt32` | Raw Windows access mask bitmask for this share ACE. | +| `mip_label_id` | `Nullable(String)` | Optional. Microsoft GUID of the MIP sensitivity label applied to this share. | +| `mip_label_name` | `Nullable(String)` | Optional. Display name of the MIP sensitivity label applied to this share. | +| `hard_delete` | `Bool` | Internal flag used by `ReplacingMergeTree` to exclude deleted rows. | + +**Relations** + +| Related table | Join column | Description | +|---------------|-------------|-------------| +| `cifs_permission` | `host`, `share_name` | Resolves NTFS ACEs that apply within this share. | + +--- + +### CIFS Sensitive Data + +Stores sensitive data classification findings — one row per taxonomy term match per file path. + +| Column | Type | Description | +|--------|------|-------------| +| `host` | `String` | Hostname of the file server. | +| `share_name` | `String` | Name of the share containing the file. | +| `path` | `String` | Full path of the file where sensitive data was detected. | +| `taxonomy_name` | `String` | Name of the taxonomy that contains the matched term (for example, `PII`). | +| `term_name` | `String` | Name of the classification term that matched (for example, `Social Security Number`). | +| `processing_time_seconds` | `Float32` | Time in seconds to classify the file. | +| `classification_method` | `Nullable(Enum8('SDK_AUTO', 'SDK_CUSTOM'))` | Optional. Whether detection used the built-in automatic classification engine (`SDK_AUTO`) or a custom classification configuration (`SDK_CUSTOM`). | +| `scan_status` | `Enum8('SUCCESS', 'ERROR')` | Whether the file was processed successfully. `SUCCESS` indicates the file was read and classified, regardless of whether sensitive data was found. `ERROR` indicates a processing failure such as a file conversion error, encryption, or unsupported format. | +| `error_message` | `Nullable(String)` | Optional. Error detail when `scan_status` is `ERROR`. Null on success. | +| `hard_delete` | `Bool` | Internal flag used by `ReplacingMergeTree` to exclude deleted rows. | + +**Relations** + +| Related table | Join column | Description | +|---------------|-------------|-------------| +| `cifs_object` | `host`, `share_name`, `path` | Resolves file system object details for this finding. | +| `cifs_sensitive_data_mip_labels` | `host`, `share_name`, `path` | Resolves MIP sensitivity label decisions applied to this file. | + +--- + +### CIFS Sensitive Data MIP Labels + +Stores Microsoft Information Protection (MIP) sensitivity label decisions for files that contain sensitive data findings. Each row records the label action Access Analyzer determined for a file based on its classification results. MIP labels are sourced from an Entra ID source group configured in the same Access Analyzer instance — Access Analyzer uses that source group to resolve label definitions and apply or recommend label changes. + +:::note +This table uses `ReplacingMergeTree(decision_timestamp)` rather than `scanned_at`. The most recent decision per file (identified by `source_id`, `host`, `share_name`, and `path`) is kept at merge time. +::: + +| Column | Type | Description | +|--------|------|-------------| +| `source_id` | `UUID` | Identifier of the Entra ID source group used to resolve MIP label definitions. | +| `host` | `String` | Hostname of the file server. | +| `share_name` | `String` | Name of the share containing the file. | +| `path` | `String` | Full path of the file this label decision applies to. | +| `mip_is_protected` | `Bool` | Whether the file is currently protected by MIP encryption. | +| `taxonomy_id` | `Nullable(UUID)` | Optional. Identifier of the taxonomy that triggered this label decision. | +| `action` | `Enum8('upgrade', 'keep', 'downgrade', 'clear', 'none')` | The label action Access Analyzer determined: `upgrade` applies a higher-sensitivity label, `downgrade` applies a lower-sensitivity label, `keep` leaves the current label unchanged, `clear` removes the label, and `none` indicates no action was taken. | +| `label_id` | `Nullable(UUID)` | Optional. UUID of the MIP sensitivity label selected by the action. | +| `label_name` | `Nullable(String)` | Optional. Display name of the MIP sensitivity label selected by the action. | +| `reason` | `Nullable(String)` | Optional. Explanation of why this label action was chosen. | +| `decision_timestamp` | `DateTime` | Timestamp when Access Analyzer made this label decision. | +| `scanned_at` | `DateTime` | Timestamp when the record was written. | +| `applied_at` | `Nullable(DateTime)` | Optional. Timestamp when the label was successfully applied to the file. Null if not yet applied. | +| `apply_error` | `String` | Error message if the label application failed. Empty string when no error occurred. | +| `apply_attempts` | `UInt8` | Number of times Access Analyzer has attempted to apply this label decision. | +| `created_at` | `DateTime` | Timestamp when this record was first created. | +| `updated_at` | `DateTime` | Timestamp when this record was last updated. | + +**Relations** + +| Related table | Join column | Description | +|---------------|-------------|-------------| +| `cifs_sensitive_data` | `host`, `share_name`, `path` | Resolves the sensitive data findings that triggered this label decision. | + +--- + +## Views + +Access Analyzer creates views that simplify common queries. Use views in preference to querying base tables directly. + +| View | Base table | Description | +|------|------------|-------------| +| `cifs_object_latest` | `cifs_object` | Returns the most recent version of each file system object, using `FINAL` to suppress duplicates. | +| `cifs_permission_latest` | `cifs_permission` | Returns the most recent version of each NTFS ACE, using `FINAL` to suppress duplicates. | +| `cifs_share_permission_latest` | `cifs_share_permission` | Returns the most recent version of each share-level ACE, using `FINAL` to suppress duplicates. | +| `cifs_sensitive_data_latest` | `cifs_sensitive_data` | Returns one aggregated row per file path, combining all taxonomy and term matches for that path. The `taxonomy_names` and `term_names` columns return arrays of distinct values grouped from individual rows. | +| `cifs_sensitive_data_mip_labels_latest` | `cifs_sensitive_data_mip_labels` | Returns the most recent label decision per file, using `FINAL` to suppress duplicates. | +| `cifs_sensitive_data_mip_labels_summary` | `cifs_sensitive_data_mip_labels` | Returns a summary of label decisions grouped by host, share, action, label name, and protection status. Includes decision counts and the timestamp range of first and last decisions. | +| `cifs_effective_permissions` | `cifs_permission_latest`, `cifs_share_permission_latest` | Joins NTFS and share permissions with resolved principal identities (local users, local groups, Active Directory users, Active Directory groups, and well-known SIDs) to produce one row per principal per path. Use this view to query who has access to a given path by name rather than by SID. | +| `cifs_effective_access` | `cifs_effective_permissions` | Computes the final effective access mask for each principal per path by combining NTFS allow and deny ACEs with share-level permissions. Use this view to determine the actual access a named user or group has to a file or directory. | diff --git a/docs/accessanalyzer/2601/gettingstarted/file-servers/set-up-source-group.md b/docs/accessanalyzer/2601/gettingstarted/file-servers/set-up-source-group.md new file mode 100644 index 0000000000..2301ca864b --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/file-servers/set-up-source-group.md @@ -0,0 +1,52 @@ +--- +title: "Set Up File Server Source Group" +description: "Configure a file server source group in Access Analyzer" +sidebar_position: 3 +--- + +# Set Up File Server Source Group + +1. Navigate to **Configuration** > **Source Groups** and click **Add Source**. The source group wizard opens. +2. Select **File Server** and click **Next**. +3. Enter a **Source Group Name**. +4. Select a service account from the **Service Account** dropdown, or click **+** to create one inline. See [Service Accounts](../../configurations/service-accounts/overview.md) for details. +5. Optionally, enter a **Domain** name to apply to all file servers in this source group. Leave blank if your servers are in a workgroup or if you want to specify credentials without a domain prefix. +6. Click **Add** under **File Servers** and enter the hostname or IP address of each file server to include. Click **Done** when finished. +7. Click **Test Connection** to verify connectivity. Each server displays a **Connected** or **Failed** status. Resolve any failures before proceeding. +8. Click **Next**. +9. Enable the scan types you want to run: + + **Access scan:** + + - Toggle **Access** to enable scanning of file permissions and access controls. + - Under **Include Shares**, select **All shares** to scan every share on the server, or **Custom selection** to specify a list of shares to include. + - Optionally, add share paths to the **Exclude Shares** field to skip specific locations. Wildcards are supported (for example, `\\fileserver\*\temp*`). + - Select **Automatically enumerate hidden shares** to include hidden shares in the scan. Use the **Exclude Hidden Shares** field to exclude specific hidden shares (for example, `ADMIN$, C$, IPC$`). + - Select **Include file-level permission data** to collect permissions at the file level in addition to folder level. This increases scan time. + - Set **Workers** to control the number of concurrent threads used during enumeration. The default is `3`. The valid range is `1–20`. + - Set **Scan Depth** to limit how many directory levels deep the scan traverses. The default is `50`. + + **Sensitive Data scan:** + + - Toggle **Sensitive Data** to enable scanning of file contents for sensitive data patterns. + - Configure share selection using the same options as the Access scan above. + - Select **Inherit from Global Settings** to use the sensitive data types configured at the system level, or disable this option to configure types for this source group specifically. + - If configuring types directly, enable each sensitive data type you want to detect and assign a classification label. + - Select **Run OCR** to scan images, screenshots, and scanned documents for sensitive text using optical character recognition (OCR). This increases processing time. + +10. Under **Scanner Location**, select **System scanner** to run scans from the Access Analyzer service, or select **Custom scanner** to use a deployed scanner. See [Scanners](../../configurations/source-groups/scanners/overview.md) for details. +11. Under **Scan Schedule**, select when to run the scan: + - **Now** — Starts the scan immediately after setup completes. + - **At** — Runs the scan once at a specific date and time. + - **Advanced** — Runs the scan on a recurring schedule defined by a cron expression. +12. Click **Complete Setup**. + +## What happens next + +Access Analyzer creates the source group and a scan for each file server you added. If you selected **Now**, the enabled scans start immediately. + +To check scan progress, navigate to **Configuration** > **Scan Executions**. + +## Edit a source group + +To modify an existing file server source group, navigate to **Configuration** > **Source Groups**, select the source group, and click **Edit**. The wizard reopens with your current configuration pre-populated. You can update the source group name, service account, file servers, and scan settings. diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/_category_.json b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/_category_.json new file mode 100644 index 0000000000..a8d05dd13b --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "SharePoint Online", + "position": 50, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/reports.md b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/reports.md new file mode 100644 index 0000000000..0c969c2a49 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/reports.md @@ -0,0 +1,17 @@ +--- +title: "Reports" +description: "Pre-built reports available for SharePoint Online source groups in Access Analyzer" +sidebar_position: 50 +--- + +# Reports + +After the first scan of a SharePoint Online source group completes, three pre-built reports become available under the Reports section. These reports help you answer key security questions about your SharePoint environment: which files carry sensitive data, how broadly content is shared, and where stale or redundant data accumulates across your sites. + +## Available reports + +| Location | Report | Description | +|----------|--------|-------------| +| Access / Shared Links Report | Shared Links Report | Shows all sharing links across your SharePoint environment, with breakdowns by sharing scope (organization, anonymous, specific people), active status, sensitive data type, and site. Use this report to identify overly broad sharing and links that expose sensitive files. | +| Content / ROT Analysis | ROT Analysis | Identifies Redundant, Obsolete, and Trivial (ROT) data across your SharePoint sites, including stale files not modified in over a year, duplicate files by content hash, and stale files containing sensitive data. Use this report to prioritize data cleanup and reduce unnecessary exposure of aging content. | +| Content / Scan Overview | Scan Overview | Summarizes the results of the most recent scan across all sites, including total site count, file count, total storage, and files with sensitive data. Use this report to confirm scan coverage and quickly identify which sites hold the most sensitive content. | diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/scanning-options.md b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/scanning-options.md new file mode 100644 index 0000000000..0c2521924d --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/scanning-options.md @@ -0,0 +1,28 @@ +--- +title: "Scanning options" +description: "Available scan types and configuration options for SharePoint Online source groups" +sidebar_position: 2 +--- + +# Scanning options + +| Scan type | Description | +| --- | --- | +| **Access scan** | Enumerates sites, document libraries, folders, and files. Collects permissions, ACLs, sharing links, and Microsoft Information Protection (MIP) sensitivity labels across the tenant. The first scan runs in full; subsequent scans collect only changes since the last run. | +| **Sensitive Data scan** | Reads file contents to classify sensitive data. Requires a completed Access scan — it uses the site and file inventory from the Access scan as its input. | + +## Access scan configuration + +| Option | Description | +| --- | --- | +| **Include site URLs** | Limits the scan to specific site collections. Enter one URL per line. Leave empty to scan all sites in the tenant. | +| **Exclude site URLs** | Excludes specific site collections from the scan. Enter one URL per line. Exclusions take precedence over inclusions. | +| **Scan OneDrive** | When enabled, includes OneDrive personal site collections in the scan. Enabled by default. | + +The Access scan also reads Microsoft Information Protection (MIP) sensitivity labels from SharePoint item metadata and stores them alongside the permission data. Access Analyzer reads existing labels only — writing or modifying MIP labels on SharePoint Online items is not supported. + +## Sensitive Data scan + +The Sensitive Data scan reads file contents to detect and classify sensitive information. It runs after the Access scan completes and uses the file inventory collected during that scan. + +Sensitive data classification policies, MIP label mappings, and OCR settings are configured globally and apply to all source groups. To configure them, navigate to **Configuration** > **Sensitive Data**. See [Sensitive Data Configuration](../../configurations/sensitive-data.md) for details. diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/schema-reference.md b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/schema-reference.md new file mode 100644 index 0000000000..b37dcaed99 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/schema-reference.md @@ -0,0 +1,166 @@ +--- +title: "Schema reference" +sidebar_position: 40 +--- + +# SharePoint Online schema reference + +Access Analyzer stores SharePoint Online scan data in the `access_analyzer` ClickHouse database. The tables below are created when you set up a SharePoint Online source group and run a scan. Use this reference when querying scan data directly or integrating Access Analyzer data with external tools. + +:::note +All tables use the `ReplacingMergeTree` engine. Duplicate rows with the same primary key are deduplicated at merge time. Query the `_latest` views to return only the most recent version of each record. +::: + +## Metadata columns + +All tables include the following columns populated by Access Analyzer during each scan: + +| Column | Type | Description | +|--------|------|-------------| +| `scan_id` | `String` | Identifier of the source group that produced this record. | +| `scan_execution_id` | `String` | Identifier of the specific scan run. | +| `scanned_at` | `DateTime` | Timestamp when the record was written. | + +--- + +## Tables + +### sharepoint_online_objects + +Stores one row per scanned SharePoint item — sites, lists, document libraries, and list items (files and folders). + +| Column | Type | Description | +|--------|------|-------------| +| `site_hostname` | `String` | Hostname of the SharePoint site collection (for example, `contoso.sharepoint.com`). | +| `site_id` | `String` | SharePoint identifier of the site collection. | +| `item_id` | `String` | Unique identifier of the item within the site. | +| `site_url` | `String` | Absolute URL of the site collection. | +| `drive_id` | `String` | Microsoft Graph drive identifier for the document library that contains this item. Empty for sites and lists that do not have a drive. | +| `drive_item_id` | `String` | Microsoft Graph drive item identifier. Empty for items that are not drive items. | +| `item_type` | `Enum8` | Type of SharePoint item. Values: `SITE`, `LIST`, `LIBRARY`, `LIST_ITEM`. | +| `name` | `String` | Display name of the item. | +| `file_extension` | `String` | File extension, including the leading period (for example, `.docx`). Empty for non-file items. | +| `relative_url` | `String` | Server-relative URL path of the item. | +| `file_size` | `Nullable(Int64)` | Optional. File size in bytes. Null for items that are not files. | +| `created_time` | `DateTime` | Timestamp when the item was created in SharePoint. | +| `created_by_id` | `String` | SharePoint user identifier of the user who created the item. | +| `created_by_email` | `String` | Email address of the user who created the item. | +| `modified_time` | `DateTime` | Timestamp of the most recent modification. | +| `modified_by_id` | `String` | SharePoint user identifier of the user who last modified the item. | +| `modified_by_email` | `String` | Email address of the user who last modified the item. | +| `parent_item_id` | `String` | `item_id` of the parent item. Empty for top-level sites. | +| `scan_status` | `String` | Result of scanning this item. Typical values: `SUCCESS`, `ERROR`. | +| `error_message` | `String` | Error detail when `scan_status` is `ERROR`. Empty on success. | +| `is_complete` | `Boolean` | Indicates whether the scan wrote all expected records for this item. Used internally to support scan resume. | + +**Primary key:** `(site_hostname, site_id, item_id)` + +**Relations** + +| Related table | Join columns | Description | +|---|---|---| +| `sharepoint_online_permissions` | `site_hostname`, `site_id`, `item_id` | All permissions assigned to this item. | +| `sharepoint_online_shared_links` | `site_hostname`, `site_id`, `item_id` | All sharing links created for this item. | +| `sharepoint_online_sensitive_data` | `drive_id`, `drive_item_id` | Classification results for this item. Only populated for drive items. | + +--- + +### sharepoint_online_permissions + +Stores one row per permission assignment. Each row represents a single principal (user or group) having a specific permission on a specific item. + +| Column | Type | Description | +|--------|------|-------------| +| `site_hostname` | `String` | Hostname of the site collection that contains the item. | +| `site_id` | `String` | SharePoint identifier of the site collection. | +| `item_id` | `String` | Identifier of the item this permission applies to. | +| `permission_id` | `String` | SharePoint identifier of the permission entry. | +| `share_id` | `String` | Identifier of the sharing link that granted this permission. Empty for direct permissions. | +| `principal_id` | `String` | Identifier of the user or group that holds the permission. | +| `principal_type` | `Enum8` | Type of the principal. Values: `USER`, `GROUP`, `SITE_USER`, `SITE_GROUP`. | +| `principal_name` | `String` | Display name of the principal. | +| `principal_email` | `String` | Email address of the principal. Empty for groups that do not have an email address. | +| `permission_type` | `Enum8` | How the permission was granted. Values: `DIRECT` (assigned directly to the item), `SHARED` (granted through a sharing link). | +| `permission_levels` | `Array(Enum8)` | Named permission levels assigned to the principal. Values: `OWNER`, `READ`, `WRITE`. | +| `effective_base_permissions` | `Array(Enum8)` | Full set of granular SharePoint base permissions the principal holds. Values include `VIEW_LIST_ITEMS`, `ADD_LIST_ITEMS`, `EDIT_LIST_ITEMS`, `DELETE_LIST_ITEMS`, `MANAGE_LISTS`, `MANAGE_PERMISSIONS`, `MANAGE_WEB`, and others as defined by the SharePoint permission model. | +| `normalized_permissions` | `FixedString(5)` | Compact bitmask representation of the permission levels. Used internally for permission comparison. | +| `parent_site_id` | `String` | Identifier of the site collection from which this permission is inherited. Empty for permissions that are not inherited. | +| `parent_item_id` | `String` | `item_id` of the item from which this permission is inherited. Empty for permissions assigned directly to this item. | +| `is_site_admin` | `Bool` | `true` if the principal is a site collection administrator. | +| `is_external_user` | `Bool` | `true` if the principal is a guest or external user. | +| `mip_label_id` | `Nullable(String)` | Optional. Microsoft GUID of the Microsoft Information Protection sensitivity label applied to the SharePoint item at the time of the scan. | +| `mip_label_name` | `Nullable(String)` | Optional. Display name of the sensitivity label identified by `mip_label_id`. | + +**Primary key:** `(site_hostname, site_id, item_id, permission_id, principal_id)` + +**Relations** + +| Related table | Join columns | Description | +|---|---|---| +| `sharepoint_online_objects` | `site_hostname`, `site_id`, `item_id` | The item this permission applies to. | +| `sharepoint_online_shared_links` | `site_hostname`, `site_id`, `item_id`, `share_id` | The sharing link that granted this permission, when `permission_type` is `SHARED`. | + +--- + +### sharepoint_online_shared_links + +Stores one row per sharing link. A sharing link may grant access to one or more principals; the corresponding permission rows appear in `sharepoint_online_permissions`. + +| Column | Type | Description | +|--------|------|-------------| +| `site_hostname` | `String` | Hostname of the site collection that contains the item. | +| `site_id` | `String` | SharePoint identifier of the site collection. | +| `item_id` | `String` | Identifier of the item this link points to. | +| `permission_id` | `String` | SharePoint permission identifier associated with this link. | +| `share_id` | `String` | Unique identifier of the sharing link. | +| `link_type` | `Enum8` | Access level granted by the link. Values: `VIEW`, `EDIT`, `EMBED`, `REVIEW`. | +| `link_url` | `String` | Full URL of the sharing link. | +| `link_scope` | `Enum8` | Audience the link is accessible to. Values: `ANONYMOUS` (anyone with the link), `ORGANIZATION` (anyone in the organization), `USERS` (specific users only). | +| `expires_on` | `DateTime` | Expiration timestamp of the link. A zero value indicates the link does not expire. | +| `is_password_protected` | `Bool` | `true` if the link requires a password to access. | +| `prevent_download` | `Bool` | `true` if the link prevents recipients from downloading the file. | + +**Primary key:** `(site_hostname, site_id, item_id, permission_id, share_id)` + +**Relations** + +| Related table | Join columns | Description | +|---|---|---| +| `sharepoint_online_objects` | `site_hostname`, `site_id`, `item_id` | The item this link provides access to. | +| `sharepoint_online_permissions` | `site_hostname`, `site_id`, `item_id`, `share_id` | Permissions granted through this link. | + +--- + +### sharepoint_online_sensitive_data + +Stores classification results from the sensitive data scan option. Each row represents one taxonomy term matched in a drive item. Multiple rows may exist for the same item when the item matches terms from multiple taxonomies. + +| Column | Type | Description | +|--------|------|-------------| +| `drive_id` | `String` | Microsoft Graph drive identifier of the document library that contains the item. | +| `drive_item_id` | `String` | Microsoft Graph drive item identifier of the classified file. | +| `taxonomy_name` | `String` | Name of the classification taxonomy (for example, `PII`, `Financial Records`). | +| `term_name` | `String` | Name of the specific classification term within the taxonomy (for example, `Credit Card Number`, `Social Security Number`). | +| `processing_time_seconds` | `Float32` | Time in seconds that the classification engine spent processing this item. | +| `classification_method` | `Nullable(Enum8)` | Optional. Method used to classify this item. Values: `SDK_AUTO` (automatic classification by the built-in engine), `SDK_CUSTOM` (classification using custom rules). | + +**Primary key:** `(drive_id, drive_item_id, taxonomy_name, term_name)` + +**Relations** + +| Related table | Join columns | Description | +|---|---|---| +| `sharepoint_online_objects` | `drive_id`, `drive_item_id` | The scanned item that produced these classification results. | + +--- + +## Views + +Access Analyzer creates views that simplify common queries. Use views in preference to querying base tables directly. + +| View | Base table | Description | +|------|------------|-------------| +| `sharepoint_online_objects_latest` | `sharepoint_online_objects` | Returns only the most recent version of each object record, deduplicated by `(site_hostname, site_id, item_id)`. | +| `sharepoint_online_permissions_latest` | `sharepoint_online_permissions` | Returns only the most recent version of each permission record, deduplicated by `(site_hostname, site_id, item_id, permission_id, principal_id)`. | +| `sharepoint_online_shared_links_latest` | `sharepoint_online_shared_links` | Returns only the most recent version of each sharing link record, deduplicated by `(site_hostname, site_id, item_id, permission_id, share_id)`. | +| `sharepoint_online_sensitive_data_latest` | `sharepoint_online_sensitive_data` | Returns one aggregated row per drive item, with `taxonomy_names` and `term_names` as arrays collecting all matched taxonomy and term names. Deduplicated by `(drive_id, drive_item_id)`. | diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/set-up-source-group.md b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/set-up-source-group.md new file mode 100644 index 0000000000..e0923fa8c9 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/set-up-source-group.md @@ -0,0 +1,57 @@ +--- +title: "Set up a SharePoint Online source group" +description: "Configure a SharePoint Online source group in Access Analyzer" +sidebar_position: 3 +--- + +# Set up a SharePoint Online source group + +1. Navigate to **Configuration** > **Source Groups** and click **Add Source**. The source group wizard opens. + +2. Select **SharePoint Online** and click **Next**. + +3. Enter a **Source Group Name**. + +4. Select a service account from the **Service Account** dropdown, or click **+** to create one inline. SharePoint Online requires a **Client ID and Certificate** service account type. See [Service Accounts](../../configurations/service-accounts/overview.md) for details. + +5. Enter the **Tenant ID** for your Microsoft Entra ID directory. This must be a valid UUID (for example, `550e8400-e29b-41d4-a716-446655440000`). + +6. Under **Certificate**, click **Generate and Download Certificate** to generate a certificate and download it to your machine. Upload this certificate to your registered Entra ID application before proceeding. See [Certificate Configuration](../../connectors/sharepoint-online/tenant-certificate-config.md) for upload steps. + + :::note + If you click **Regenerate Certificate** in the future, the new certificate must be uploaded to your Entra ID App Registration to replace the old one. Removing the old certificate from the App Registration is a manual step in the Azure portal — Access Analyzer cannot remove it on your behalf. + ::: + +7. Click **Test Connection** to verify that Access Analyzer can authenticate to your SharePoint Online tenant. Resolve any failures before proceeding. + +8. Click **Next**. + +9. Under **Scan Configuration**, configure the options for the scans you want to run: + + - **Include site URLs** — Limits the scan to specific site collections. Enter one URL per line. Leave empty to scan all sites in the tenant. + - **Exclude site URLs** — Excludes specific site collections from the scan. Exclusions take precedence over inclusions. + - **Scan OneDrive** — When enabled, includes OneDrive personal site collections in the scan. + + See [Scanning options](./scanning-options.md) for a full description of available scan types and options. + +10. Under **Scan Schedule**, select when to run the scan: + + - **Now** — Starts the scan immediately after setup completes. + - **At** — Runs the scan once at a specific date and time. + - **Advanced** — Runs the scan on a recurring schedule defined by a cron expression. + +11. Click **Complete Setup**. + +## What happens next + +Access Analyzer creates the source group and begins scanning your SharePoint Online environment. If you selected **Now**, the scan starts immediately. + +To check scan progress, navigate to **Configuration** > **Scan Executions**. + +## Edit a source group + +To modify an existing SharePoint Online source group, navigate to **Configuration** > **Source Groups**, select the source group, and click **Edit**. The wizard reopens with your current configuration pre-populated. You can update the source group name, service account, tenant ID, scan configuration, and scan schedule. + +:::note +Updating the service account replaces the certificate used to authenticate with SharePoint Online. Ensure the new service account's certificate is uploaded to your registered Entra ID application before saving. +::: diff --git a/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/sharepoint-online.md b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/sharepoint-online.md new file mode 100644 index 0000000000..517738c004 --- /dev/null +++ b/docs/accessanalyzer/2601/gettingstarted/sharepoint-online/sharepoint-online.md @@ -0,0 +1,42 @@ +--- +title: "SharePoint Online Scanning Overview" +description: "Overview of SharePoint Online scanning capabilities and prerequisites in Access Analyzer" +sidebar_position: 1 +--- + +# SharePoint Online Scanning Overview + +Access Analyzer scans SharePoint Online sites to map permissions, enumerate sharing links, and locate sensitive data across your tenant's document libraries and sites. It surfaces over-permissioned sites, anonymous and organization-wide sharing links, and files that contain sensitive content — giving security teams the information they need to reduce external exposure, enforce sharing policies, and meet cloud data governance requirements. + +## Prerequisites + +Before setting up a SharePoint Online source group, confirm that your environment meets the requirements below. The source group wizard connects to SharePoint Online over HTTPS using certificate-based authentication, so the Access Analyzer server must be able to reach the Microsoft identity platform and an app registration must be configured in your tenant. The certificate is generated by the wizard — you'll need the application's Client ID before you begin. + +### Service account + +Access Analyzer uses a Client ID and Certificate service account to authenticate with SharePoint Online. Only the Client ID is entered when creating the service account — the certificate is generated automatically during source group setup when you click **Generate and Download Certificate**. You then upload the certificate to your registered Entra ID application before the connection can be tested. + +See [Client ID/Certificate service account](../../configurations/service-accounts/client-id-certificate.md) to create the service account and [SharePoint Online Connector Requirements](../../connectors/sharepoint-online/overview.md) for instructions on registering the application. + +### Network requirements + +| Protocol | Port | Destination | +| --- | --- | --- | +| HTTPS | 443 | Microsoft identity platform (`login.microsoftonline.com`) | +| HTTPS | 443 | Microsoft Graph API (`graph.microsoft.com`) | +| HTTPS | 443 | SharePoint Online (`.sharepoint.com`) | + +### Before you begin + +- A registered application in your Entra ID tenant. +- The application's **Tenant ID** and **Client ID**. +- A Client ID and Certificate service account created in Access Analyzer. +- Network connectivity from the Access Analyzer server to port 443 confirmed. + +:::note +Access Analyzer reads MIP sensitivity labels on SharePoint Online files during Sensitive Data scans. Labels are collected and surfaced in scan results — no changes are made to labels on any scanned file. +::: + +:::note +**Sensitive Data scans require a completed Access scan.** The Access scan builds the site and document library inventory that the Sensitive Data scan uses. Run the Access scan first, then enable Sensitive Data on a subsequent scan. Enabling both on the very first scan is supported but will extend the initial scan duration. +::: diff --git a/docs/accessanalyzer/2601/index.md b/docs/accessanalyzer/2601/index.md new file mode 100644 index 0000000000..74e897b9fa --- /dev/null +++ b/docs/accessanalyzer/2601/index.md @@ -0,0 +1,21 @@ +--- +title: "Netwrix Access Analyzer Documentation" +description: "Netwrix Access Analyzer 1.0 product documentation - on-premises DSPM platform for data security and access analysis" +sidebar_position: 1 +--- + +# Netwrix Access Analyzer Documentation + +Netwrix Access Analyzer is an on-premises Data Security Posture Management (DSPM) platform that helps organizations discover, classify, and monitor sensitive data across enterprise file systems. Deployed entirely within your own infrastructure, it provides comprehensive visibility into data access patterns, identifies compliance risks, and enables data governance — without sending data to the cloud. + +## Key Capabilities + +- **Data Source Scanning** — Connect to CIFS/SMB file shares and other on-premises data repositories to discover and analyze data +- **Sensitive Data Discovery** — Detect sensitive data using built-in and custom regex patterns with taxonomy-based classification +- **Identity and Access Management** — Sync users and groups from Active Directory and Entra ID to analyze permission paths +- **Dashboards and Reporting** — Visualize security posture with built-in dashboards and embedded Metabase reports + +## Documentation Sections + +- [Overview](overview/overview.md) — Introduction to the product, key concepts, requirements, and installation +- [Getting Started](gettingstarted/active-directory/active-directory.md) — Step-by-step guides for your first scans and syncs diff --git a/docs/accessanalyzer/2601/install/_category_.json b/docs/accessanalyzer/2601/install/_category_.json new file mode 100644 index 0000000000..4ec6b4da75 --- /dev/null +++ b/docs/accessanalyzer/2601/install/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Installation", + "position": 12, + "collapsed": true, + "collapsible": true +} diff --git a/docs/accessanalyzer/2601/install/identity-provider.md b/docs/accessanalyzer/2601/install/identity-provider.md new file mode 100644 index 0000000000..ef670d89e9 --- /dev/null +++ b/docs/accessanalyzer/2601/install/identity-provider.md @@ -0,0 +1,552 @@ +--- +title: "Configure Identity Provider" +description: "Deployment steps for connecting an Identity Provider to Access Analyzer using the installer" +sidebar_position: 50 +--- + +# Configure Identity Provider + +:::note +This article is for the team performing the Access Analyzer deployment. It covers the installer flags required to connect an identity provider at install time. If you are an application administrator setting up user accounts after the IdP connection is in place, see [Identity Provider](../configurations/identity-provider.md). +::: + +**Related reading:** + +- [Quick Install](quickinstall.md) — Active Directory deployment using environment variables, end-to-end +- [Installer Command Reference](install-commands.md) — full catalog of every installer flag and environment variable +- [TLS Certificate Requirements](system/certificates.md) — certificate formats, SAN rules, CA bundle preparation + +Access Analyzer supports connecting an identity provider (IdP) so users authenticate through your organization's directory rather than with local credentials. IdP federation is **optional** — if you omit `--idp-type` at install time, Access Analyzer is deployed without Keycloak and uses local accounts only. + +When `--idp-type` is configured, the installer automatically: + +1. Deploys Keycloak (v26.5.3) as part of the cluster +2. Waits for Keycloak to become healthy +3. Creates the IdP federation using the flags you provided +4. Enables OIDC authentication in the Access Analyzer application + +## Before you begin + +Confirm the following before running the installer with IdP flags: + +- The Access Analyzer cluster system requirements are met — see [Hardware and System Requirements](system/requirements.md) +- TLS certificates are prepared and placed on the VM — see [TLS Certificate Requirements](system/certificates.md) +- You have collected the required credentials from the customer's IdP or directory administrator (see [Identity Provider — Part 1](../configurations/identity-provider.md#part-1-configure-your-identity-provider)) +- For LDAP/AD: the Access Analyzer server has network access to the LDAP server on port 636 (LDAPS) or 389 (LDAP) +- For a private CA certificate: you have the PEM file available on the server and will pass `--ca-bundle ` to the installer + +:::warning +`--hostname` is required and must: + +- Be a real DNS hostname (not an IP address — IPs will not work because the browser TLS handshake requires the hostname in the certificate's SAN). +- Be lowercase, and match lowercase in the certificate SAN list. Keycloak's OIDC issuer URL is derived from this value; a case mismatch between SAN and browser-normalized hostname produces HTTP 401 at sign-in. +- Resolve the same from client browsers and in-cluster pods. The installer configures the in-cluster rewrite automatically; the customer is responsible for the public DNS record or `/etc/hosts` entry that client browsers use. +- Avoid the `.local` and `.localhost` TLDs — both break in-cluster DNS resolution and silently break OIDC login flows. + +For full certificate format and preparation details, see [TLS Certificate Requirements](system/certificates.md). +::: + +## Choosing an IdP type + +| `--idp-type` value | Use case | +| --- | --- | +| `ad` | Active Directory via LDAP (on-premises) | +| `ldap` | Generic LDAP | + + + +:::note +`--idp-alias` must match `[A-Za-z0-9._-]+` — letters, digits, hyphens, underscores, and dots only. Spaces are not allowed. The alias is shown as the label on the login button. +::: + + + +## Configure Active Directory + +:::tip +For a step-by-step end-to-end walkthrough using environment variables (recommended for most customers), see the [Quick Install](quickinstall.md). The section below is the flag-level reference. +::: + +**Required flags:** `--idp-type ad`, `--idp-alias`, `--ldap-url`, `--ldap-bind-dn`, `--ldap-users-dn` + +**Optional:** `--ldap-email-attribute` (default: `mail`) + +**Prompted secret:** LDAP bind credential — entered interactively, never written to disk or logs + +If your domain controller's LDAPS certificate is signed by an internal CA not in the OS trust store (typical for on-prem AD), pass the root CA cert via `--ca-bundle`. Without it, Keycloak's LDAPS handshake to the DC will fail with a TLS trust error. The CA that signed the DC's LDAPS certificate may be different from the CA that signed your Access Analyzer server's TLS certificate — verify the DC's cert chain specifically. See [TLS Certificate Requirements](system/certificates.md) for details on assembling the CA bundle. + +```bash +export LICENSE_KEY='[YOUR_LICENSE_KEY]' + +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --hostname aa2601.corp.example.com \ + --tls-cert /opt/dspm-tls/aa2601.crt \ + --tls-key /opt/dspm-tls/aa2601.key \ + --ca-bundle /opt/dspm-tls/ca-bundle.crt \ + --idp-type ad \ + --idp-alias active-directory \ + --ldap-url ldaps://dc.corp.example.com:636 \ + --ldap-bind-dn "CN=svc-dspm,OU=ServiceAccounts,DC=corp,DC=example,DC=com" \ + --ldap-users-dn "OU=Users,DC=corp,DC=example,DC=com" +``` + +Replace the LDAP URL with the customer's domain controller address (LDAPS on port 636 recommended). When prompted, enter the bind account password. + +The `ad` type uses Active Directory–specific defaults: `sAMAccountName` for the username attribute and `objectGUID` for the UUID attribute. + +## Configure Generic LDAP + +Use this type for OpenLDAP and other non-AD LDAP directories. + +**Required flags:** `--idp-type ldap`, `--idp-alias`, `--ldap-url`, `--ldap-bind-dn`, `--ldap-users-dn` + +**Optional:** `--ldap-email-attribute` (default: `mail`) + +**Prompted secret:** LDAP bind credential + +```bash +export LICENSE_KEY='[YOUR_LICENSE_KEY]' + +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --hostname aa2601.corp.example.com \ + --tls-cert /opt/dspm-tls/aa2601.crt \ + --tls-key /opt/dspm-tls/aa2601.key \ + --ca-bundle /opt/dspm-tls/ca-bundle.crt \ + --idp-type ldap \ + --idp-alias ldap \ + --ldap-url ldaps://ldap.corp.example.com:636 \ + --ldap-bind-dn "CN=svc-dspm,OU=ServiceAccounts,DC=corp,DC=example,DC=com" \ + --ldap-users-dn "OU=Users,DC=corp,DC=example,DC=com" +``` + +As with the Active Directory section above, pass `--ca-bundle` with the root CA cert that signed the directory's LDAPS certificate when it is not in the OS trust store. + +The `ldap` type uses generic LDAP defaults: `uid` for the username attribute and `entryUUID` for the UUID attribute. + +## Recover from a failed IdP configuration + +If IdP configuration fails after the cluster is already running, use `--configure-idp-only` to retry without reinstalling K3s or ArgoCD: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --configure-idp-only \ + --idp-type ad \ + --idp-alias active-directory \ + --ldap-url ldaps://dc.corp.example.com:636 \ + --ldap-bind-dn "CN=svc-dspm,OU=ServiceAccounts,DC=corp,DC=example,DC=com" \ + --ldap-users-dn "OU=Users,DC=corp,DC=example,DC=com" +``` + +:::note +`--configure-idp-only` does not require `--license-key`. It skips all infrastructure provisioning steps and runs only the IdP configuration phase. +::: + +## Next steps + +After the installer completes IdP configuration, the application administrator must pre-provision user accounts in Access Analyzer before any users can sign in. See [Identity Provider](../configurations/identity-provider.md#pre-provision-user-accounts). + +## Manual configuration reference + +The installer automates all of the following steps. Use this section only if you need to reconfigure or troubleshoot an IdP connection on a cluster that is already running, without re-running the installer. + +### Authenticate to the Keycloak Admin CLI + +Run this step before any manual configuration. It authenticates the Keycloak Admin CLI inside the pod using the bootstrap credentials injected at deploy time. + +```bash +kubectl exec -n access-analyzer statefulset/keycloak -- bash -c ' + /opt/keycloak/bin/kcadm.sh config credentials \ + --server http://localhost:8080/auth \ + --realm master \ + --user "$KC_BOOTSTRAP_ADMIN_USERNAME" \ + --password "$KC_BOOTSTRAP_ADMIN_PASSWORD"' +``` + +:::note +The bootstrap admin credentials are read from environment variables already present in the pod. Don't pass them as command-line arguments — they would appear in Kubernetes audit logs. +::: + + + +### Configure LDAP / Active Directory — manual + +**Required values:** LDAP server URL, service account DN, service account password, users base DN + +**Step 1 — Create the LDAP User Federation component** + +```bash +LDAP_ID=$(kubectl exec -i -n access-analyzer statefulset/keycloak -- bash <"]' \ + -s 'config.bindDn=[""]' \ + -s 'config.bindCredential=[""]' \ + -s 'config.usersDn=[""]' \ + -s 'config.usernameLDAPAttribute=["sAMAccountName"]' \ + -s 'config.rdnLDAPAttribute=["cn"]' \ + -s 'config.uuidLDAPAttribute=["objectGUID"]' \ + -s 'config.userObjectClasses=["person,organizationalPerson,user"]' \ + -s 'config.searchScope=["2"]' \ + -s 'config.importEnabled=["true"]' \ + -s 'config.syncRegistrations=["false"]' \ + -o --fields id | grep '"id"' | sed 's/.*"id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' +EOF +) +``` + +**Step 2 — Add the email attribute mapper** + +```bash +kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh create components -r dspm \ + -s name=email-mapper \ + -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper \ + -s providerId=user-attribute-ldap-mapper \ + -s "parentId=$LDAP_ID" \ + -s '{"ldap.attribute":["mail"],"is.mandatory.in.ldap":["false"],"always.read.value.from.ldap":["false"],"read.only":["true"],"user.model.attribute":["email"]}' +``` + +**Step 3 — Add the provider attribute mapper** + +```bash +kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh create components -r dspm \ + -s name=ldap-provider-attribute \ + -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper \ + -s providerId=hardcoded-attribute-mapper \ + -s "parentId=$LDAP_ID" \ + -s '{"attribute.value":["ldap"],"user.model.attribute":["ldap_provider"]}' +``` + +**Step 4 — Add the realm protocol mapper** + +```bash +kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh create protocol-mappers/models -r dspm \ + --body '{ + "name": "ldap-identity-provider-claim", + "protocol": "openid-connect", + "protocolMapper": "oidc-usermodel-attribute-mapper", + "config": { + "user.attribute": "ldap_provider", + "claim.name": "identity_provider", + "jsonType.label": "String", + "id.token.claim": "true", + "access.token.claim": "true", + "userinfo.token.claim": "true" + } + }' +``` + +### Verify the configuration — manual + +**LDAP (component check only):** + +```bash +TYPE=ldap ./scripts/verify-idp-config.sh +``` + +**LDAP (with connectivity test):** + +```bash +TYPE=ldap \ +LDAP_URL= \ +LDAP_BIND_DN= \ +LDAP_BIND_CREDENTIAL= \ +./scripts/verify-idp-config.sh +``` + +## Troubleshooting IdP configuration + +IdP configuration runs as the final step of the installer, after Keycloak is healthy. A failure here means the cluster and applications are running correctly — only the identity federation is missing. + +### Check the installer log + +The installer log contains the full `kcadm.sh` output: + +```bash +grep -A 20 "Configuring IdP federation" /var/log/dspm-installer.log +``` + +### Common error messages + +| Message | Likely cause | +| --- | --- | +| `Failed to authenticate with Keycloak admin CLI` | Keycloak pod not ready; check pod status below | +| `409 Conflict` from `kcadm.sh create` | An IdP with this alias already exists in Keycloak | +| `PKIX path building failed` in Keycloak logs (LDAP sign-ins fail silently) | CA bundle is missing the LDAPS DC's CA — see [TLS Certificate Requirements](system/certificates.md#multi-domain-and-multi-ca-environments) | + +### Check Keycloak pod health + +```bash +# Confirm the pod is running +kubectl get pods -n access-analyzer -l app=keycloak + +# Check for recent errors in the Keycloak logs +kubectl logs -n access-analyzer statefulset/keycloak --tail=50 +``` + +### Retry using --configure-idp-only + +If the cluster is healthy but IdP configuration failed, re-run the installer with `--configure-idp-only`. This skips K3s and ArgoCD entirely and retries only the Keycloak configuration: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --configure-idp-only \ + --hostname aa2601.corp.example.com \ + --ca-bundle /opt/dspm-tls/ca-bundle.crt \ + --idp-type \ + --idp-alias \ + # ...same --idp-* flags used during the original install +``` + +`--configure-idp-only` does not require `--license-key`. + +### If retry fails with 409 Conflict + +If a previous partial run created the IdP instance in Keycloak before failing (for example, during mapper creation), the retry fails with a `409 Conflict`. Remove the partial IdP first using `kcadm.sh` inside the Keycloak pod. + +Authenticate first: + +```bash +kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh config credentials \ + --server http://localhost:8080/auth --realm master \ + --user "$KC_BOOTSTRAP_ADMIN_USERNAME" \ + --password "$KC_BOOTSTRAP_ADMIN_PASSWORD" +``` + +For **LDAP or AD** IdPs (child mappers cascade-delete automatically): + +```bash +LDAP_ID=$(kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh get components -r dspm \ + -q name= \ + -q type=org.keycloak.storage.UserStorageProvider \ + --fields id -c \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(d[0]['id'] if d else '')") + +kubectl exec -n access-analyzer statefulset/keycloak -- \ + /opt/keycloak/bin/kcadm.sh delete components/"${LDAP_ID}" -r dspm +``` + +Replace `` with the value that was passed to `--idp-alias` during the failed install. Then re-run `--configure-idp-only`. diff --git a/docs/accessanalyzer/2601/install/install-commands.md b/docs/accessanalyzer/2601/install/install-commands.md new file mode 100644 index 0000000000..e7bc9bbd12 --- /dev/null +++ b/docs/accessanalyzer/2601/install/install-commands.md @@ -0,0 +1,261 @@ +--- +title: "Installer Command Reference" +description: "Options you can pass to the Access Analyzer installer to customize your deployment" +sidebar_position: 20 +--- + +# Installer Command Reference + +Access Analyzer is installed using a single curl command that downloads and runs the installer. You can pass options to this command to customize how the product is deployed on your server. Most installations need only a license key and accept all defaults. + +## Before You Run the Installer + +### Set your license key + +Export your license key as an environment variable before running any installer command. This keeps the key out of your shell history and makes it available to the installer automatically. + +```bash +export LICENSE_KEY='[YOUR_LICENSE_KEY]' +``` + +Replace `[YOUR_LICENSE_KEY]` with the license key provided by Netwrix. All examples on this page assume you have exported this variable. + +:::warning +Your license key authenticates access to the Netwrix package registry. Don't share it, commit it to version control, or leave it visible in script files. +::: + +### Choose an installer version + +**Without specifying a version**, the installer downloads the latest stable release automatically. This is appropriate for initial deployments and when you're ready to take the latest release: + +```bash +# Set the Keygen license key variable +export LICENSE_KEY='[YOUR_LICENSE_KEY]' + +# Run installation +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash - +``` + +**To pin to a specific release** — recommended when you want to control when upgrades happen during your organization's patching cycle — export the version before running the same curl command: + +```bash +# Set the Keygen license key variable +export LICENSE_KEY='[YOUR_LICENSE_KEY]' + +# Pin to a specific release version +export DSPM_TARGET_REVISION='[VERSION]' + +# Run installation +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash - +``` + +:::note +The version number for each Access Analyzer release will be published here before general availability. Replace `[VERSION]` with the version string provided in the release notes. +::: + +## Environment Variables + +Most options can be set as environment variables instead of command-line flags. This is the recommended style for scripted or automated deployments — see the [Quick Install](quickinstall.md) for an end-to-end example. + +Export the variables before running the installer. When the same option is set as both an environment variable and a command-line flag, the flag takes precedence. + +| Environment variable | Equivalent flag | Example | +| --- | --- | --- | +| `LICENSE_KEY` | `--license-key` | `NWRX-XXXX-XXXX-XXXX` | +| `DSPM_HOSTNAME` | `--hostname` | `aa2601.corp.example.com` | +| `DSPM_TARGET_REVISION` | `--target-revision` | `1.*` (latest stable) or `0.3.362-dev` | +| `SIZE` | `--size` | `1` (default), `2`, up to `10` | +| `TLS_CERT_FILE` | `--tls-cert` | `/opt/dspm-tls/aa2601.crt` | +| `TLS_KEY_FILE` | `--tls-key` | `/opt/dspm-tls/aa2601.key` | +| `TLS_CA_BUNDLE_FILE` | `--ca-bundle` | `/opt/dspm-tls/ca-bundle.crt` | +| `IDP_TYPE` | `--idp-type` | `ad`, `ldap` | +| `IDP_ALIAS` | `--idp-alias` | `corporate-ad` (no spaces) | +| `LDAP_URL` | `--ldap-url` | `ldaps://dc01.example.com:636` | +| `LDAP_BIND_DN` | `--ldap-bind-dn` | `CN=svc-dspm,OU=ServiceAccounts,DC=example,DC=com` | +| `LDAP_USERS_DN` | `--ldap-users-dn` | `CN=Users,DC=example,DC=com` | +| `LDAP_EMAIL_ATTRIBUTE` | `--ldap-email-attribute` | `mail` (default) | +| `LDAP_BIND_CREDENTIAL` | (secret — see Quick Install) | (see Quick Install) | +| `POSTGRES_DATA_DIR` | `--postgres-data-dir` | `/mnt/ssd/postgres` | +| `CLICKHOUSE_DATA_DIR` | `--clickhouse-data-dir` | `/mnt/nvme/clickhouse` | +| `ACCEPT_WARNINGS` | `--accept-warnings` | `true` | +| `LOG_LEVEL` | `--log-level` | `info` (default), `debug`, `warn`, `error` | +| `HTTP_PROXY` / `HTTPS_PROXY` | (no flag) | `http://proxy.example.com:8080` | +| `NO_PROXY` | (no flag) | `localhost,127.0.0.1,.svc,.cluster.local` | +| `SKIP_AV_CHECK` | (no flag) | `true` | +| `DRY_RUN` | `--dry-run` | `true` | + +:::note +`LDAP_BIND_CREDENTIAL` is the only secret environment variable, and the installer does not actually honor it — the installer always reads the bind password via an interactive prompt or piped stdin, overwriting any exported value. See [Quick Install — Step 3](quickinstall.md#step-3-download-and-run-the-installer) for the two supported ways to provide the password. +::: + +## Running the Installer + +When you run the curl command above, the installer automatically: + +1. Runs preflight checks to verify your system meets requirements +2. Installs Kubernetes (k3s v1.33.4, the version validated by Netwrix for this release) +3. Deploys ArgoCD as the GitOps controller +4. Pulls and deploys the Access Analyzer application stack from the Netwrix registry +5. Waits for all components to become healthy + +Installation typically takes 15–30 minutes depending on network speed and hardware. + +### Passing additional options + +To customize the installation, add options after `bash -s --`. Everything after `--` is forwarded to the installer: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- --dry-run +``` + +For options that take a value, such as custom storage paths: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --postgres-data-dir /mnt/ssd/postgres \ + --clickhouse-data-dir /mnt/nvme/clickhouse +``` + +The available options are described in the sections below. + +### Validate before installing (dry run) + +To check system readiness without making any changes, add `--dry-run`: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- --dry-run +``` + +Dry run performs all preflight checks and shows what the installer would do, without modifying the system. Use this before deploying to production to confirm your server meets requirements. + +## Customizing the Installation + +### Directing database storage to a dedicated volume + +By default, the PostgreSQL and ClickHouse databases store data on the root filesystem. For production deployments, direct each database to a dedicated volume to keep database growth from filling your root disk: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- \ + --postgres-data-dir /mnt/ssd/postgres \ + --clickhouse-data-dir /mnt/nvme/clickhouse +``` + +Each directory must already exist and be writable before the installer runs. The path must: + +- Start with `/` (absolute path) +- Not be a system directory (`/bin`, `/etc`, `/usr`, `/var/log`, and others) +- Not contain special characters: `"`, `'`, `\`, `` ` ``, or `$` + +### Scaling resources for larger servers + +The `--size` option scales CPU and memory allocations for all Access Analyzer workloads. The default value of `1` suits the minimum recommended hardware (24 GB RAM, 6 vCPUs). Increase this on servers with more resources: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- --size 2 +``` + +The valid range is `1` through `10`. Contact Netwrix Support for guidance on which value is appropriate for your server. + +### Increasing log verbosity + +If an installation fails and you need more detail to diagnose the problem, run with debug logging: + +```bash +curl -sLfo - "https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-install.sh?auth=license:$LICENSE_KEY" | bash -s -- --log-level debug +``` + +The log is written to `/var/log/dspm-installer.log`. Accepted values are `debug`, `info`, `warn`, and `error`. The default is `info`. Terminal progress output is not affected — only the log file verbosity changes. + +## Identity Provider Flags + +The table below lists every IdP flag the installer accepts. For end-to-end examples, see one of these walkthroughs: + +- [Quick Install](quickinstall.md) — Active Directory deployment using environment variables (recommended for most customers) +- [Configure Identity Provider](identity-provider.md) — example commands for Active Directory and LDAP, plus recovery with `--configure-idp-only` + +| Flag | Default | Description | +| --- | --- | --- | +| `--idp-type ` | — | Federation type: `ad`, `ldap` | +| `--idp-alias