docs/_index.md --- title: "The runZero Platform" --- ## Introduction runZero is a total attack surface and exposure management platform that combines active scanning, passive discovery, and API integrations to deliver complete visibility into managed and unmanaged assets across IT, OT, IoT, cloud, mobile, and remote environments. runZero can be used as a hosted service (SaaS) or managed [on-premise](self-hosting.md). The runZero stack consists of one more Consoles, linked [Explorers](installing-an-explorer.md) that run as light-weight services on network points-of-presence, and a [command-line tool](using-the-cli.md) that can be used for offline data collection. runZero can be managed through the web interface, via API, or for self-hosted customers, on the command line. - [What is runZero?](what-is-runzero.md) - [Ready to get started?](getting-started.md) - [Looking for an `llms.txt`?](https://help.runzero.com/llms.txt) ## Offline documentation - [runZero User Guide (PDF)](https://help.runzero.com/docs/runzero-manual.pdf) - [runZero API (PDF)](https://help.runzero.com/docs/runzero-api.pdf) - [runZero API HTML (ZIP)](https://help.runzero.com/docs/runzero-api.zip) - [runZero Software Bill of Materials (SBOM PDF)](https://help.runzero.com/docs/runzero-bom.pdf) --- docs/what-is-runzero.md --- title: "What is runZero?" --- ## runZero {#what-is-runzero-intro} runZero is a total attack surface and exposure management platform that combines active scanning, passive discovery, and API integrations to deliver complete visibility into managed and unmanaged assets across IT, OT, IoT, cloud, mobile, and remote environments. runZero can be used as a hosted service (SaaS) or managed [on-premise](self-hosting.md). The runZero stack consists of one more Consoles, linked [Explorers](installing-an-explorer.md) that run as light-weight services on network points-of-presence, and a [command-line tool](using-the-cli.md) that can be used for offline data collection. runZero can be managed through the web interface, via API, or for self-hosted customers, on the command line. ### Data Sources {#what-is-runzero-datasources} * **Active Scans**: runZero's best-in-class [active scan engine](discovering-assets.md) is fast, accurate, and safe for all environments, with support for a massive number of [protocols](troubleshooting-protocols-scanned.md) and [applications](data-dictionary.md). * **Passive Traffic Sampling**: runZero's [passive traffic sampling engine](traffic-sampling.md) scales with available resources and works with broadcast traffic, SPAN ports, and encapsulated streams. Any runZero Explorer can be used for passive traffic sampling, regardless of location, configuration, or resources. * **API Integrations**: runZero supports [inbound](integrations-inbound.md) and [outbound](integrations-outbound.md) integrations with major Cloud, Endpoint, CMDB, and Endpoint providers. In addition to the native options, customers can create their own integrations using the [Custom Integration API](integrations-inbound.md/#custom-integrations) and [Custom Integration Scripts](custom-integration-scripts.md). ### Live Inventory {#what-is-runzero-inventory} * **Assets**: runZero tracks all [assets](understanding-assets.md) across the environment; including cloud, mobile, endpoint, server, OT, IoT, and everything else in between. Assets are correlated and merged across data sources to provide a multi-perspective snapshot of all organization resources. The asset inventory supports deep search, configurable columns, and simple export. * **Services**: runZero tracks all identified network services, via active scans, passive discovery, and integrations (where applicable). The services inventory simplifies exposure management tasks and enables deep search and exports. * **Screenshots**: runZero takes a snapshot of each exposed web service included in active scans. The screenshot inventory allows security teams to visually inspect unknown devices and services. * **Software**: runZero identifies network-exposed software and imports software records from API integrations. The result is a software inventory that can be used to quickly identify specific packages and versions across the environment. * **Vulnerabilities**: runZero reports vulnerabilities based on identified exposures and imports vulnerability data from API integrations. The vulnerability inventory is provided as both a detailed, per-asset inventory, as well as a grouped view that simplifies investigation into specific issues. * **Certificates**: runZero identifies SSL/TLS certificates, including those that are expired or soon-to-expire. The certificate inventory includes all relevant metadata, such as issuer, expiration date, and certificate chain. * **Wireless**: runZero active scans also enumerate wireless access points within range of the Explorer running the task. This inventory includes the BSSID, SSID, encryption settings, and signal strength. * **Users and Groups**: runZero imports user and group information from directory services, including Active Directory, Azure Active Directory (Entra ID), and Google Workspace. The user and group inventories can be used to identify accounts with specific attributes, such as expired passwords and excessive group permissions. ### Reports {#what-is-runzero-reports} runZero includes a comprehensive set of reports that cover everything from [layer-2 topology maps](switch-topology-report.md) to outliers and asset risk. In addition to pre-defined reports, most attributes within an asset or service can be used to create a grouped report with a single click. For deep customization, the runZero [Export API](exporting-asset-data.md) provides CSV and JSON(L) formats with arbitrary search filters, which can be used to drive analytics platforms like Tableau and PowerBI. ### Monitoring and Alerts {#what-is-runzero-alerts} runZero provides monitoring and [alert](managing-alerts.md) capabilities that can trigger based on changes to the inventory, new results for custom search [queries](search-query-syntax.md), and any system-level event (of dozens). These alerts can be delivered either in-product, by email, or to a webhook destination, including Slack channels. In addition to alerts, rules, and custom queries, [goals](goal-tracking.md) and custom dashboard widgets can be defined to track progress towards a specific outcome. --- docs/getting-started.md --- title: "Getting started" --- To get started, you'll need to ((sign up)) for a runZero account. The default account is a trial of the full runZero Platform. After the trial expires, you will have the option to convert to the free Community Edition or purchase a subscription. - [Sign up for a runZero account](https://www.runzero.com/try/) - Read up on [creating an account](creating-account.md) for help activating your account, changing your password, and adding a profile picture. - Once your account is set up, there are a couple of paths you can take to deploy runZero. - [Quickstart](getting-started.md/#quickstart-guide) - [Full deployment plan](getting-started.md/#full-deployment-plan) ## Quickstart guide {#quickstart-guide} The quickstart path is ideal for those who want to jump into using runZero and explore its core functionalities. This section covers the initial setup, running basic scans, and configuring integrations. ### 1. Set up an Explorer {#set-up-explorer} To begin asset discovery, you need to deploy an Explorer: - Navigate to Deploy > Deploy Explorers in the runZero Console. - Review the system requirements and choose the appropriate binary for your platform. - Ensure the Explorer connects to your organization. Each download link is organization-specific. ### 2. Run your first scan {#run-first-scan} Once the Explorer is installed: - Go to Scan in the console. - Click Start standard scan and configure the discovery scope: - Choose an Explorer. - Set the target subnets or CIDR ranges. - Run the scan and monitor progress from the console.
Note
We recommend starting with a `/24` or handful of small CIDR blocks to verify connectivity in the network and then scaling out from there.
### 3. Configure integrations {#configure-integrations} Enhance your data with third-party integrations: - Navigate to Integrate. - Select and configure supported integrations for EDR, Vulnerability Management, Cloud, etc. - [Documentation for each inbound integration](integrations-inbound.md) is available. - Ensure appropriate permissions are set in the integrated systems. - Run sync tasks to import data and merge with existing asset information. ### 4. Review scan results {#review-scan-results} After the scan completes: - Check results under Inventory > Assets. - Use the Query library to better understand misconfigurations and other noteable findings in the inventory. - Review reports and customize dashboards for deeper insights. - Here are a few sample reports to check out: - SNMP default communities - SSH authentication methods - TLS supported versions
Note
If you have no results with the `matches:>0` search, you may need to wait for the metrics to be calculated. You can see the status of the metrics calculations here.
## Full deployment plan {#full-deployment-plan} For organizations planning a production deployment, careful preparation ensures a smooth and scalable setup. Follow these steps: ### 1. Plan your deployment {#plan-deployment} - Determine the goals for asset visibility, network segmentation, or compliance. - Ensure adequate resources for Explorers and network access points. - Familiarize yourself with runZero-specific terms in the glossary. ### 2. Initial setup {#initial-setup} - Deploy Explorers across key network segments. - Configure credentials for access to devices and services (e.g., SNMP, EDR, MDM, etc). - Use network communication guidelines to verify connectivity. ### 3. Run discovery and assess {#run-discovery-assess} - Perform discovery scans on all required segments. - Validate data integrity and optimize scan settings as needed. - Identify any scanning gaps and adjust configurations. ### 4. Automate and optimize {#automate-optimize} - Implement scan schedules for continuous monitoring. - Use integrations for enriched asset data. - Set up alerting and reporting tailored to your organization’s needs. ### 5. Rollout and monitor {#rollout-monitor} - Deploy across remaining network segments based on your plan. - Monitor scan results and network health regularly. - Document configurations and processes for ongoing management. For detailed instructions, refer to the [production deployment documentation](deployment-plan.md). For assistance, please contact [support](mailto:support@runzero.com). --- docs/creating-account.md --- title: "Creating an account" --- To get started, you'll need to ((sign up)) for a runZero account. The default account is a trial of the full runZero Platform. After the trial expires, you will have the option to convert to the free Community Edition or purchase a subscription. [Sign up for a runZero account](https://www.runzero.com/try/) ## ((Activating your account)) After you sign up for an account, we'll email you a link to activate your account. If you don't see an email from us, check your spam folder. Open the link in the email to go to the **Activation** page. Follow the instructions on the page to activate your account. You'll need to provide your name, set up a password, specify your location, and accept our [privacy policy](https://www.runzero.com/legal/privacy/) and [terms of service](https://www.runzero.com/legal/terms/). After activating your account, you'll be taken directly to the runZero Console. Your new account has administrative access, so you will be able to manage [sites](sites.md), [organizations](organizations.md), [users](managing-your-team.md), and [Explorers](installing-an-explorer.md). If you have any trouble creating your account, please contact [support](mailto:support@runzero.com). ## Changing your password To change your password, go to your [account settings](https://console.runzero.com/settings). You'll need to provide your current password before you can enter a new one. All ((passwords|password rules)) must contain: - At least 8 characters - At least 1 uppercase character - At least 1 lowercase character - At least 1 number ## Updating your profile picture User ((profile images)) are managed through [Gravatar](https://gravatar.com/) and associated with your email address. If you don't have an account, [sign up for one](https://en.gravatar.com/support/about-profiles/). --- docs/installing-an-explorer.md --- title: "Installing an Explorer" aliases: [ "/docs/installing-an-agent/" ] --- runZero requires the use of at least one ((Explorer)) within your environment to enable active and passive network discovery. The Explorer should be installed on a system with reliable connectivity to the network you want to discover. For internal networks, runZero works best when installed on a system with a wired (vs wireless) connection. For ((external network discovery)), nearly any cloud provider with a reliable connection should do. If the runZero Explorer is installed in a ((container)) or ((virtualized system)), ensure that it has direct access to the network (host networking in ((Docker)), bridged networking in ((VMware)), etc). SaaS customers with a Platform license can use the runZero hosted Explorers at no additional cost. [View an interactive version of this diagram](https://www.figma.com/proto/JgnLAWYFpODvNHQ272nmM4/Architecture-Diagram?page-id=0%3A1&type=design&node-id=687-1473&viewport=-51%2C403%2C0.08&t=lQUeTS4hgEfxLB9E-1&scaling=contain&starting-point-node-id=1%3A1430) ![runZero deployment diagram](img/deployment-diagram.svg) ## ((Installation)) To install the runZero Explorer, sign in to the runZero Console and switch to the Organization that should be associated with the Explorer. Explorer downloads are then available by selecting ((Deploy)) in the left navigator and choosing the Deploy Explorers sub-menu. **Note:** The Explorer download link is specific to your active organization and **using the wrong link can result in a new Explorer being associated with the wrong organization**. ((Download)) the correct binary for your system from the [Explorer download page](https://console.runzero.com/deploy/download/explorers). For most systems, select the 64-bit (x86_64) architecture. For macOS, you will need to select 64-bit Intel (x86_64) or ARM (Apple M*), depending on your hardware. For ((embedded devices)), such as the Raspberry Pi 3+, choose the ARM7 architecture. Windows binaries are signed with a valid Authenticode signature, which should be validated before the executable is launched. The Explorer installation process requires administrative privileges. On Windows, a ((UAC)) prompt may be displayed. On Linux and macOS the downloaded binary should be made executable (`chmod u+x runzero-agent.bin`) and then executed with root privileges (`sudo` or from root shell). In either case, the Explorer should install itself as a system service and start immediately, displaying a new entry in the [Explorers page](https://console.runzero.com/deploy/explorers). ## ((System requirements)) ### Windows * Windows Server 2016 or Windows 10 Build 1604+ * Processor running at 2.0 GHz or faster * At least 16GiB of memory (8GiB for small environments) * At least 1GB of free storage space #### Limitations * The Trellix agent for Windows appears to interfere with network scans and traffic capture. Please use a system without the Trellix agent for active scans or passive network sampling. Alternatively, switching the Trellix HIDS agent from "block" to "monitor" may allow successful scans. * Earlier Windows versions may be able to run the Explorer, but are not officially supported. * Windows Explorers are limited to a single concurrent scan or passive task due to performance limitations of the raw packet driver. ### Linux * Kernel version 3.2 or later * Processor running at 2.0 GHz or faster * At least 16GiB of memory (8GiB for small environments) * At least 1GB of free storage space Linux ARM devices with limited processing power and memory, such as the Raspberry Pi, can run the runZero Explorer, but may have trouble scanning larger networks, or running integrations with large amounts of data. ### MacOS * macOS 11 (Big Sur) or newer * Processor running at 2.0 GHz or faster * At least 16GiB of memory (8GiB for small environments) * At least 1GB of free storage space Due to Notary requirements introduced in macOS Catalina (10.15), using the **curl** download method provided on the deployment page in the Console is required. ### BSD variants * Processor running at 2.0 GHz or faster * At least 16GiB of memory (8GiB for small environments) * At least 1GB of free storage space Requires root access to a system running a recent version of the operating system. FreeBSD 11.2 or newer, recent versions of NetBSD/DragonFly/OpenBSD. ## Configuration {#configuration}
Note
Existing installations may refer to `Rumble` in the directory name, service name, and binary names. `Rumble, Inc`` was the previous name of our business and new installations will only refer to `runZero`, our new name. going forward.
The Explorer can be configured by setting variables in a `config.txt` file located in the same directory as the executable. On Windows this file should be created in `C:\Program Files\runZero\config.txt`, while other platforms should use `/opt/runzero/bin/config.txt`. In addition to `config.txt`, the legacy `.env` name is also supported. If the file `/etc/runzero/config` is present, this will be preferred as the configuration settings for the Explorer. The format of this file is `VAR=VAL` with one variable per line. ### Configuration file locations {#configuration-locations} **Windows**: `C:\Program Files\runZero\config.txt` **Other Platforms**: `/opt/runzero/bin/config.txt` ## ((Web screenshots)) The scanner will try to work with any Chrome, Chromium, or Edge version available and indicate the browser path and version within the Explorers list in the web console. If no supported browser is found, we recommend installing the official [Google Chrome](https://www.google.com/chrome/) package for your operating system in order to enable [web ((screenshots))](managing-explorers.md#screenshot-capabilities). To install the latest Chrome package on Debian-based Linux installations (including Ubuntu): ```bash curl -o chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \ sudo apt install ./chrome.deb ``` To install the latest Chrome package on RedHat-based Linux installations (including Fedora, CentOS, Rocky, and Alma): ```bash curl -o chrome.rpm https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm && \ sudo dnf install ./chrome.rpm ``` The following variables in the environment or configuration file to change web screenshot behavior: The `RUNZERO_CHROMIUM_IGNORE_SYSTEM` parameter can be set to `true` to ignore system Chromium paths for screenshots. The `RUNZERO_CHROMIUM_AUTOMATIC_INSTALL` parameter can be set to `true` to enable automatic Chromium installation if necessary. This pulls directly from the Google and Puppeteer CDNs. The `RUNZERO_CHROMIUM_DEBUG` parameter can be set to `true` to enable detailed Chromium process logging while screenshots are taken. The `RUNZERO_CHROMIUM_USER` parameter can be set to a valid system username on non-Windows systems. When the scanner is run as root, the Chromium process will be run as this user account (and default GID). The `RUNZERO_CHROMIUM_CACHE_DIR` parameter can be set to a directory path to use for automatic Chromium installations (or installations managed through content updates). This defaults to `/opt/runzero/chromium` on non-Windows and the binary directory plus `\chromium` on Windows. This directory contains a file called `LATEST.txt` that contains a numeric revision, which refers to a sub-directory named `chromium-[revision]`, which includes a copy of the Chromium installation. The `RUNZERO_CHROMIUM_DISABLE_CHROMEDP` parameter can be set to `true` to disable the debug protocol capture mode (now the default). The `RUNZERO_CHROMIUM_DISABLE_CHROMECL` parameter can be set to `true` to disable the command-line headless `--screenshot` capture mode (used as a fallback otherwise). ## Network communication The Explorer connects to the runZero Console on TCP port 443 using TLS. This connection is used for Explorer registration, job scheduling, status messages, and submission of completed scan jobs. For completely offline environments, the [runZero CLI](https://console.runzero.com/deploy/download/cli) can be used to create scan data files that can be uploaded later via the [Inventory](https://console.runzero.com/inventory) `Import` action. The console is used for automatic updates of the Explorer executable. The specific IP addresses used depend on your deployment model and region. For customers using the SaaS console, the following static IPs are associated with the runZero consoles. ### United States The console hostname is `console.runzero.com`. IPv4 * 13.248.161.247 * 76.223.34.198 IPv6 * 2600:9000:a415:cd87:fbe5:476a:3533:69f2 * 2600:9000:a716:ee91:85f9:3c9:48c9:59b9 ### Germany The console hostname is `console-eu.runzero.com`. IPv4 * 15.197.131.232 * 3.33.248.90 IPv6 * 2600:9000:a603:e925:542d:6d40:6897:bc3a * 2600:9000:a70e:635f:71bd:bb0a:8e43:9466 ### NAT The Explorer should be run on a system with a full bidirectional network connection. It should **not** be run on a system behind a NAT gateway. This includes virtual machines, which should be set up with bridged network adapters. Juniper DDoS protection is known to break runZero scans. ### Proxy support Please note that certain web proxies that perform TLS inspection do not handle Websocket communication properly and TLS inspection will need to be disabled for the runZero Explorer to successfully connect. The most popular product with this problem is the Sophos (previously Cyberoam) security appliance. Websense users may need to add a [bypass rule](https://www.websense.com/content/support/library/web/hosted/admin_guide/ssl_bypass.aspx) for `console.runzero.com`. Proxy support is handled automatically in most cases. On the Windows platform, proxy information is read from the registry keys (used by Chrome, Edge, and IE). The proxy can also be configured by setting the `HTTPS_PROXY` environment variable. The value of the `HTTPS_PROXY` environment variable should be a hostname and port (`proxy.example.com:8080`) or just a hostname (`proxy`). Environment variables are read from your configuration file. Please view the [Configuration](installing-an-explorer.md#configuration-locations) section to see how to set environment variables. The common option is to create a file named `config.txt` in the same directory as the Explorer binary and set the environment variables in the format described below. It's also possible to use a SOCKS proxy by setting `HTTPS_PROXY` to a `socks5` URL, for example `HTTPS_PROXY=socks5://socks.example.com:1080`. It's also possible to set a specific proxy override for AWS connections, by specifying `HTTPS_PROXY_AWS`. This setting takes priority over any base `HTTPS_PROXY` setting for the Explorer. The Explorer will attempt to use the configured proxy for each probe. If it doesn't succeed, it will try making a direct connection. This means both proxy and non-proxy connection attempts may appear in logs. Using only proxies to try to hide or anonymize Explorer connections is not supported. ### TLS configuration The minimum and maximum version of TLS used by the Explorer for outbound communication to the console can be configured through environment variable and the configuration file. The `TLS_VERSION_MIN` and `TLS_VERSION_MAX` variables can be set to any of `1.0`, `1.1`, `1.2`, and `1.3`. The default configuration is to use a minimum version of TLS 1.2 and a maximum of TLS 1.3. If a maximum version is set to a value lower than the minimum value, the maximum will be set to the minimum value. runZero does not recommend using TLS versions prior to 1.2. The following example will configure the Explorer to only speak TLS version 1.3. ``` TLS_VERSION_MIN=1.3 TLS_VERSION_MAX=1.3 ``` ## Restarting an Explorer The easiest way to restart an Explorer is to force a software update from the cloud console. Otherwise, you can find the service on the host machine and restart it by hand. On Linux or Mac, you can run `/opt/runzero/bin/runzero-agent-[uuid] restart` where `[uuid]` is the ID of the organization the Explorer belongs to. On Linux systems you can also use `systemd` to restart Explorers. First obtain the name of the Explorer (runzero-agent-[uuid]) service: ```bash systemctl | grep runzero-agent ``` Then restart the service using this name: ```bash systemctl restart runzero-agent-[uuid] ``` A `kill -9` of the Explorer pid should cause a restart as well. On macOS, you can use `launchctl` to restart the Explorer: ```bash launchctl kickstart -k runzero-agent-[uuid] ``` As with Linux, the `[uuid]` is the organization UUID, which you can find by looking at the `runzero-agent-*` filename in `/opt/runzero/bin` On Windows, you can use the Services console to restart the Explorer like any other background service. ## Removing an Explorer The easiest way to remove an Explorer is to use the [Explorers](https://console.runzero.com/deploy/explorers) page and locate the Explorer you want to remove, then click the _Delete Explorer_ trash bin icon under the _Actions_ column. This will remove the service and terminate the current Explorer process. In addition, you can remove all online Explorers by clicking the _Manage All Explorers_ menu and choose the _Uninstall All Online Explorers_ option. If you would like to remove an Explorer without using the runZero Console, there are a couple of options. On the Windows platform, each Explorer will be listed in Programs and Features (as the runZero Agent), and can be uninstalled like any other application. On all platforms, including Windows, the Explorer can uninstall itself if run with the `uninstall` argument from a root or Administrator shell: ### Removal on Windows ```console c:\Program Files\runZero\runzero-agent-[uuid].exe uninstall ``` ### Removal on Other Platforms ```bash /opt/runzero/bin/runzero-agent-[uuid] uninstall ``` ## Log management The Explorer logs to a file and to standard output by default. On Windows the default log file location is the installation directory (`C:\Program Files\runZero` or `C:\Program Files\Rumble` for old installations) while other platforms log to the files `/var/log/runzero.log` and `/var/log/runzero.err`. The default configuration limits log files to 100MiB, creates three backups, and expires logs after 90 days. These defaults can be be changed by setting the following values in the `$BIN/config.txt` file: * The `RUNZERO_AGENT_LOG_MAX_SIZE` setting controls the maximum log size in mibibytes. The default is **100**. * The `RUNZERO_AGENT_LOG_MAX_BACKUPS` setting controls the number of backup files created by log rotation. The default is **3**. * The `RUNZERO_AGENT_LOG_MAX_AGE` setting controls the maximum age in days, this applies to all files, including backups. The default is **90**. * The `RUNZERO_AGENT_LOG_COMPRESS` setting determines whether to gzip compress the backups. The default is **false**. * The `RUNZERO_AGENT_LOG_STDOUT` setting determines whether to write logs to standard output. The default is **true**. On Linux this results in logs being written to the system log when the Explorer is started by systemd or upstart. On macOS this results in separate logs viewable in the Console application under "Log Reports" when the Explorer is started by launchd. * The `RUNZERO_AGENT_LOG_FILE` setting determines whether to write logs to a log file as described above. The default is **true**, set to `false` to disable log file writing. The Explorer must be restarted for these settings to take effect. ## Certificate Authorities (CAs) The runZero Explorer uses the system-installed certificate authorities to validate TLS connections in addition to an internal CA certificate bundle. By default, both the system certificate roots, and the bundled roots are considered for all secure TLS connections, including Starlark-based custom integrations. This behavior can be controlled via environment variables (set in the `$BIN/config.txt` file or at the system level): * The `RUNZERO_TLS_IGNORE_SYSTEM_ROOTCA` setting can be set to **true** to ignore the system CA roots. * The `RUNZERO_TLS_IGNORE_EMBEDDED_ROOTCA` setting can be set to **true** to ignore the bundled CA roots. * The `RUNZERO_TLS_ADDITIONAL_ROOTCA` setting can be set to a file path containing additional CA roots in PEM format. ## Manual mode If a supported system service manager, such as systemd or upstart, is not detected, the runZero Explorer will switch to manual mode, running in the foreground, and replacing and re-executing its own binary as new updates become available. For temporary Explorer installations or to run the Explorer in a container environment, the argument "manual" can be specified: `$ sudo ./runzero-agent.bin manual` ## Storage locations The runZero Explorer installs into `%PROGRAMFILES%\runZero` on Windows and `/opt/runzero/bin` on all other platforms. Temporary files are stored in the default operating system locations. These locations can be overridden using the `config.txt` file (see the above [Configuration](#configuration) section). Note that the Explorer service needs to be restarted (or force updated) for these changes to take effect. Older installations may still refer to the `Rumble` versions of the previously mentioned directories and `.env` instead of `config.txt` for environment overrides. On Windows, the temporary file location is chosen from the first non-empty environment value of `TMP`, `TEMP`, or `USERPROFILE`, falling back to the Windows directory. To override this location, set an entry in `config.txt` like the following: `TMP=D:\Storage\runZero` On all other platforms, the temporary file location is chosen based on the value of `TMPDIR`, falling back to `/tmp` otherwise. To override this location, set an entry in `config.txt` like the following: `TMPDIR=/home/storage/runzero` Any scans that fail to upload are stored in the runZero Explorer installation directory and can be imported into the platform manually or using the runZero CLI's `scan --import` and `scan --upload` options. ## Container installations The runZero Explorer can run in standard container environments, with three important caveats: 1. runZero Explorer binaries are updated frequently and these updates include time-sensitive security coverage. If the container filesystem is read-write, the Explorer will automatically update, but revert to an older state on container restart. We recommend rebuilding the container image frequently or having the entry point of the container retrieve and run the latest binary for your organization on startup. If the container is read-only, no updates will be applied, and each task will be delayed by up to five minutes as the Consoles tries to update anyways. 2. The container must run as root with full privileges in order to access the raw network device. The specific network parameters differ by container runtime, but typically this means using a bridged, macvlan, or host (not host-only) networking option when deploying the container. Without raw network access many of runZero's features will not work, including ARP scans, IPv6 neighbor discovery, TCP SYN scans, and passive network sampling via SPAN ports. 3. The container must be configured with a persistent `RUNZERO_AGENT_HOST_ID` environment variable and only one container with this ID should be run at a given time. Without this setting, the Explorer will re-register on every container restart, and if more than one container share the same identifier, task processing will not work correctly as the container fight over the task status. This host ID environment should be set to a unique 32-character hexadecimal string. To generate a suitable identifier, the `openssl` tool may be used: ```bash openssl rand -hex 16 01b0283809b24511929d0b062bd36109 ``` Here is a sample Containerfile you can edit and use: ```bash # # Sample Containerfile for running the runZero Explorer in a container, with # screenshot support. # FROM debian:stable WORKDIR /opt/runzero # Ensure curl is available and install tools for wireless scanning. # RUN apt update && apt install -y curl wireless-tools # Install Chrome for screenshots. # RUN curl -o chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \ apt install -y ./chrome.deb # Set AGENT_URL to be the download URL for your Linux runZero Explorer. To # find your URL, go to https://console.runzero.com/deploy/download/explorers # and click on the first URL box to copy it to the clipboard. # ENV AGENT_URL=https://console.runzero.com/download/explorer/DT[uniqueToken]/[versionID]/runzero-agent-linux-amd64.bin # This ID is used to track the Explorer even if the container is rebuilt. # Set it to a unique 32 character hex ID. You can generate one via: # # $ openssl rand -hex 16 # ENV RUNZERO_AGENT_HOST_ID=[UNIQUE-ID] # If you need to set environment variables to change the Explorer behavior, # you can do so via the ENV directive. Example: # # ENV RUNZERO_AGENT_LOG_DEBUG=true ADD ${AGENT_URL} runzero-agent.bin RUN chmod +x runzero-agent.bin # For full functionality the runZero CLI needs to send and receive raw # packets, which requires elevated privileges. USER root # The argument `manual` tells runZero not to look for SystemD or upstart. ENTRYPOINT [ "/opt/runzero/runzero-agent.bin", "manual" ] ``` This containerfile works with podman as well as Docker. Note that because of the requirement for root privileges, you should start the container as root. For the best results, run the container with the `--privileged` option to allow the Explorer to listen to network traffic. ## Automated installations The Explorer will automatically install when executed if root or administrative privileges are available. On Linux and BSD systems, automatic installation depends on the presence of a supported init service like systemd or upstart. If no supported init service is found, the Explorer will instead run in manual mode, automatically overwriting and re-executing itself with each update. To automatically deploy an Explorer on systems without a supported init service, the Explorer should be executed in the background and with the `nohup` wrapper. On Windows systems, the Explorer will automatically install when run interactively or when the `updater` parameter is passed to the binary. For environments where MSIs are required, the [Explorer MSI](explorer-msi.md) wrapper can be used to deploy an Explorer from the runZero Console or a local mirror. ## AWS EC2 installations The runZero Explorer can be run in an AWS EC2 instance. However, there are a number of configuration changes required to avoid packet loss when scanning. * DNS resolution from EC2 to the AWS DNS server has [a fixed cap of 1024 packets per second](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-limits) which cannot be increased. To avoid this, set a custom list of non-AWS nameservers in the scan configuration advanced section. * Any Security Group without a `0/0` rule results in [connection tracking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-connection-tracking.html), which has an undocumented limit on connections per instance type. Avoid this by adding `0/0 allow` for ICMP/UDP inbound and outbound for the Explorer instance. Also add a `0/0 allow` for outbound TCP connections. (Inbound TCP is not currently required for runZero scans, but may be needed in the future for callback protocols.) * Overall packet rates have [undocumented limits which depend on instance type](https://www.bluematador.com/blog/packets-per-second-in-ec2-vs-amazons-published-network-performance). You will need to experiment with sizing your Explorer instances until scans are consistent for a given scan rate. We hope to gather and share data on appropriate instance sizes soon. The Explorer should work well deployed to a memory optimized, compute optimized, or general compute instance. Since the Explorer can make full use of multi-core systems, you may want to target the number of cores to the number of simultaneous scans. You probably won't want to run larger scans on an instance with less than 32GiB of RAM. --- docs/explorer-msi.md --- title: "Automated MSI deployments" aliases: ["/docs/agent-msi"] --- runZero uses dynamically generated binaries for the runZero Explorer downloads and this doesn't always play well with MSI-based installation methods. To work around this issue, we have provided a shim ((MSI package)) that can be used with ((automated installers)). This package has a valid Authenticode signature and can also be verified using the [runZero Verifier](binary-verification.md).
Note
Some components of the application still reference the name "Rumble" for backwards compatibility. All new installations will use runZero for directory, file, and user names.
To use this package, deploy it with the `URL` parameter specified as the organization-specific download URL from the runZero Console Explorers section. ```bash msiexec /i runzero-explorer-installer-amd64.msi URL=https://console.runzero.com /download/explorer/DT[uniqueToken]/[versionID]/runzero-explorer-windows-amd64.exe ```
Note
The above command should be entered as one long line with a single URL parameter, but is shown wrapped here.
The MSI shim will verify that the URL contains a valid runZero Explorer binary and install it normally. **Warning**: Note that installing with the `/a` parameter will not work and `/i` must be used instead. ## Binary downloads | Build | SHA256 | |-------|-----| | [runZero Explorer Installer MSI x86 64-bit][msi64] | [sha-256][msi64-sum] | | [runZero Explorer Installer MSI x86 32-bit][msi32] | [sha-256][msi32-sum] | [msi64]: https://public.runzero.com/builds/runzero-explorer-msi/runzero-explorer-installer-amd64.msi [msi64-sum]: https://public.runzero.com/builds/runzero-explorer-msi/runzero-explorer-installer-amd64.msi.sum [msi32]: https://public.runzero.com/builds/runzero-explorer-msi/runzero-explorer-installer-386.msi [msi32-sum]: https://public.runzero.com/builds/runzero-explorer-msi/runzero-explorer-installer-386.msi.sum --- docs/installing-explorer-on-raspberry-pi.md --- title: Installing on a Raspberry Pi description: How to install a runZero Explorer on Raspberry Pi for remote deployment. date: 2021-04-20 --- The runZero Explorer enables discovery scanning. In most cases, you can deploy an Explorer on an existing system that has connectivity to the network you want to discover. However, there may be times when the traditional deployment model may not work for you. Some locations, like retail stores or customer sites, may not have staff or hardware available to install the Explorer, making remote deployment a bit tricky. In these types of scenarios, you can install a runZero Explorer on a ((Raspberry Pi)) and send the device to the location for them to plug into their network. ## What you'll need - Raspberry Pi 4 Model B (4GB or 8GB), Raspberry Pi Compute Module 4, or Raspberry Pi 400 - At least 1GB free of storage space on your Raspberry Pi's MicroSD card after installing the operating system ## Connecting to your Raspberry Pi via SSH In this section, we're going to show you how to SSH to your Raspberry Pi and install the Explorer from your terminal. ### Step 1. Enable SSH on your Raspberry Pi Before you can connect to your Raspberry Pi, make sure to [enable SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/README.md) on the device. You can add a file called ssh.txt at the root of the SD card and reboot the Raspberry Pi. The contents of the file can be empty. On reboot, the Pi looks for the SSH file and enables SSH if it finds the file. ### Step 2. Update the password for your Raspberry Pi If you enable SSH on your Raspberry Pi, you must [update your credentials](https://www.raspberrypi.org/documentation/linux/usage/users.md). Log in as the `pi` user and use the `passwd` command to change the default password. Entering the `passwd` command will prompt you for your current password to authenticate before you can change it. ### Step 3. Copy the Explorer instructions - Go to your [console](https://console.runzero.com). Verify you are in the right organization. runZero keys your Explorer's download link to the organization you are currently viewing to associate them together. - Go to the [Explorer deployment page](https://console.runzero.com/deploy/download/explorers) and select **Linux Distributions**, and then choose Linux ARM 32-bit V7. Note that Raspbian uses a 32-bit kernel by default, even on 64-bit Raspberry Pi hardware. - Click the instructions at the bottom of the Linux installation page to place the commands into your clipboard. ### Step 4. Install the Explorer
Note
Some components of the application still reference the name "Rumble" for backwards compatibility. The documentation will be updated as these are changed.
Paste the installation command into the terminal after connecting to the Raspberry Pi via SSH. The URL in the command links the installation to your active organization and will be different from the example below. ``` me@mac ~ % ssh pi@hostIP pi@host's password: pi@raspberrypi:~ $ sudo bash root@raspberrypi:/home/pi# cd Downloads root@raspberrypi:/home/pi# curl -o runzero-explorer.bin https://console.runzero.com/download/explorer/DT[uniqueToken]/[versionID]/runzero-explorer-linux-arm7.bin && chmod u+x runzero-explorer.bin && sudo ./runzero-explorer.bin ``` The Explorer automatically installs itself in `/opt/runzero` and sets up a systemd service with the name `runzero-agent-`. The service automatically starts on boot. ## Next steps Your Raspberry Pi is now set up to use as a runZero Explorer box and ready to be sent wherever you need. You can always view and manage your [registered Explorers](https://console.runzero.com/deploy/explorers) from your console. --- docs/managing-explorers.md --- title: "Managing Explorers" aliases: [ "/docs/managing-explorers/" ] --- The runZero Explorer is a lightweight scan engine that enables network and asset discovery. You should have at least one ((Explorer)) deployed. After deployment, you can manage your Explorers from the [Deploy page](https://console.runzero.com/deploy/explorers) in your runZero web console. ## Viewing all Explorers For each Explorer, you can see: - The Explorer status (whether it is communicating with runZero) - The OS it is running on - Its name - Any site it is associated with - Its IP addresses - The software version it is running - Whether the version of npcap installed is up-to-date, if the OS is Windows (see [upgrading npcap](#upgrading-npcap) below) - The CPU architecture of the host machine - Any tags associated with the Explorer - The status of its last scan - Its capabilities, like Chrome support ## Screenshot capabilities To capture screenshots, Chrome must be installed. You can check if an Explorer has ((screenshot)) capabilities by looking for the Chrome icon in the _Capabilities_ column. Here's what each icon means: - Green icon - The Explorer has access to a Google Chrome binary and can take screenshots. - Red icon - No suitable Chrome binary was found. ## Searching for Explorers You can use the search bar to find Explorers. The query syntax is similar to other search bars in runZero, with keywords to filter by specific fields: | Keyword | Search by | Example | |------------------|------------------|-------------------------| | `arch:` | CPU architecture | `arch:amd64` | | `name:` | assigned name | `name:scanner.local` | | `address:` | IP address | `address:10.0.1.200` | | `capability:` | capabilities | `capability:screenshot` or `capability:aws` | | `tag:` | assigned tag | `tag:dev` | | `npcap_version:` | npcap version | `npcap_version:1.31` | ## Explorer actions Each Explorer has a set of action buttons that allow you to: - **Reinstall an Explorer** - Performs a ((reinstall)) or ((upgrade)) of the Explorer. The current Explorer will download the latest Explorer code from runZero, and then run the install process. - **Configure an Explorer** - You can associate the Explorer with a specific site, enable recurring speed tests, and add tags to it. You can also set the maximum number of concurrent scans allowed. A single Explorer can be configured to run multiple tasks at once. - **Reassign an Explorer** - You can reassign an Explorer to a different organization within your account or even to a different runZero client account entirely. - **Remove an Explorer** - If the Explorer is running, the Explorer will be asked to uninstall itself from the host machine. If the Explorer is not running, you can still tell runZero to forget about it. This is useful if you have decommissioned the machine the Explorer was running on or uninstalled the Explorer manually. If the Explorer runs again after runZero has been told to forget it, it will be readded to the registered Explorers list. ## Bulk management operations Bulk operations allow you to perform a set of actions to multiple Explorers at one time. Bulk actions are available from the _Manage all Explorers_ menu. You can bulk: - **Update all online Explorers** - Tells all Explorers–that are up and communicating with runZero–to upgrade their software. - **Forget all offline Explorers** - Clears all Explorers currently offline, and makes runZero forget them. No data will be lost. If any of the Explorers are reactivated, they will be added back to the active list. - **Uninstall all online Explorers** - Tells all online Explorers to uninstall themselves from their host systems. - **Automatically assign sites** - Runs through all of the Explorers that are not currently assigned to a specific site. It checks their IP address against the CIDR IP ranges of the registered subnets of all sites in the current organization. If the Explorer's IP address only matches a single site, the Explorer is assigned to that site. ## Viewing Explorer details Clicking on an Explorer's name takes you to a page showing the diagnostic information for that Explorer, including its software version, available memory, and network interfaces. At the bottom of the page is a diagnostics text area. Clicking the _Update Diagnostics_ button will fetch an updated list of all sub-processes active within the Explorer. This is useful to send to runZero support if you are having problems with a particular Explorer. ### Internet speed tests {#explorer-speed-tests} Explorers can be configured to run internet speed tests on recurring hourly intervals, or run on-demand as desired. The most recent speed test results are shown in the "Internet speed tests" table, which can be useful in monitoring the network performance of the Explorer's host machine over time. Speed tests can be initiated on-demand by clicking the "Start speed test" button, which will run a single speed test and update the table with the results. To configure recurring speed tests: 1. From the [**Registered Explorers**](https://console.runzero.com/deploy/explorers/) page, select the Explorer you wish to run speed tests. 2. In the "Explorer details" card, click the "Edit" button and enter a number into the "Speed tests" input for how often you want the speed test to run, in hours. 3. Click **Save** to confirm your configuration and initiate recurring speed tests at the selected interval. **Note:** your Explorer version must be up-to-date to run speed tests. If needed, click the "Update Explorer" button to update it to the latest version and then configure it as desired. The table of speed test results can also be downloaded in CSV, JSON or JSONL format by clicking the "Download speed test results" button and selecting the desired file type. Additionally, any time a speed test is run, a `speedtest-completed` event will be generated in the runZero audit log with its results for tracking purposes. ### Traffic sampling {#explorer-traffic-sampling} The Explorer details page is also where users can configure traffic sampling. 1. From the [**Registered Explorers**](https://console.runzero.com/deploy/explorers/) page, select the Explorer you wish to configure to perform traffic sampling. 1. In the traffic sampling card, configure the following options: - **Site**: Specify the site the assets discovered as a result of Traffic Sampling will be added to. - **Discovery scope**: List the IP addresses or CIDR networks that traffic sampling will observe on this Explorer. - **Asset tags** (optional): List the tags you want applied to assets discovered through traffic sampling. - **Excluded hosts** (optional): List the IP addresses or CIDR networks that traffic sampling will exclude from the results. - **Interfaces**: Toggle the switches for the interfaces you want this Explorer to listen on. 1. Click **Save** to save your configuration and initiate the traffic sampling task. Once configured, traffic sampling can be disabled by returning to this page and toggling off the selected interfaces. Upon saving, the traffic sampling tasks will automatically stop. ## Explorer Groups With runZero Explorer groups, a user can configure a logical grouping of Explorers that will intelligently distribute scheduled tasks amongst themselves. Using Explorer groups makes it easier to schedule a large number of tasks, without having to manage which Explorer they run on. **Creating an Explorer group:** Explorer groups can be created and managed from the [Explorer groups](https://console.runzero.com/deploy/explorer-groups) page. When creating a new Explorer group, configure a name, description, site, and select the Explorers you want in the group. It should be noted that all Explorers in the group must be set to the same site as the group. This is due to the fact that there is no guarantee of which Explorer in the group will run a given task. If this was not enforced, assets could be merged into the wrong site. **Using an Explorer group:** When configuring a scan or integration task, select an Explorer group and the group will elect the best fit Explorer for the tasks. ## Upgrading npcap On Windows, runZero uses a licensed third-party library called [npcap](https://nmap.org/npcap/) for access to raw network traffic. Other software installed on the Explorer's host machine may also use ((npcap)), and sometimes will have installed obsolete versions of the software. This can cause reliability problems. runZero will alert you to obsolete versions of npcap by displaying a warning icon in the list of Explorers. However, runZero cannot yet reliably upgrade npcap for you. runZero can't automatically upgrade npcap/winpcap, as it tends to be shared between applications, and forcing an upgrade from the runZero side can break other services (EDRs, Wireshark, etc). **To upgrade npcap manually:** 1. Stop any running runZero services. This can be done using the Windows Services app. You'll need to look for "runZero Network Discovery Explorer". 2. Stop any other running software which uses npcap. 3. Uninstall Winpcap and any npcap installations via the Windows Control Panel. 4. Reboot the computer. runZero will restart automatically, and install the latest npcap. --- docs/binary-verification.md --- title: "Verifying binaries" --- runZero uses dynamically generated binaries for the runZero Console, CLI, and Explorer downloads. Although Windows binaries have a valid Authenticode signature, all binaries also contain a secondary, internal signature. Dynamic binaries make it easy to deploy Explorers that connect back to the right organization, but present a challenge for independent integrity validation. To enable verification of the internal signature, we offer the **runZero Verifier**. This verification tool can confirm whether a given binary contains a valid ((internal signature|binary signature)), in addition to any existing Authenticode signatures. To get started, download the latest version of the ((verifier)) from the bottom of this page along with the PGP signature file for the selected architecture. The runZero Verifier is always signed by PGP Key ID [`60EBAAE9AEF08C6D`](https://www.runzero.com/.well-known/security.pub.asc). To validate the signature of the runZero Verifier for Windows 64-bit, you will need a [GPG](https://gpg4win.org/download.html) client and to run the following commands: ``` C:\> curl -s https://www.runzero.com/.well-known/security.pub.asc | gpg --import C:\> gpg --verify runzero-verifier-3.1.0-windows-amd64.exe.asc ``` Successful validation will show a valid signature by key ID `9B5DAFF7D43349298A3039BD60EBAAE9AEF08C6D`. ``` gpg: Signature made Sun 07 Aug 2022 11:33:15 AM CDT gpg: using RSA key 9B5DAFF7D43349298A3039BD60EBAAE9AEF08C6D gpg: issuer "security@runzero.com" gpg: Good signature from "runZero Security " [unknown] ``` The warning below is expected and does not indicate a problem with the signature: ``` gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. ``` Once the runZero Verifier itself has been validated, it can be used to check the signature of any runZero binary: ``` C:\> runzero-verifier-3.1.0-windows-amd64.exe runzero-explorer-3.1.0-windows-amd64.exe runzero-explorer-3.1.0-windows-amd64.exe: VALID SIGNATURE ``` A failed validation will show the error `Invalid or missing signature` and the verifier will set exit status to 1. ## Binary downloads {#verifying-binary-downloads} ### Windows {#binary-verification-windows} | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier x86 64-bit][windows-amd64-exe]| [pgp signature][windows-amd64-asc]| [sha-256][windows-amd64-sum] | | [runZero Verifier x86 32-bit][windows-386-exe]| [pgp signature][windows-386-asc]| [sha-256][windows-386-sum] | ### Linux {#binary-verification-linux} | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier x86 64-bit][linux-amd64-bin]| [pgp signature][linux-amd64-asc]| [sha-256][linux-amd64-sum] | | [runZero Verifier x86 32-bit][linux-386-bin]| [pgp signature][linux-386-asc]| [sha-256][linux-386-sum] | #### Additional Linux builds | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier ARM v5 32-bit][linux-arm5-bin]| [pgp signature][linux-arm5-asc]| [sha-256][linux-arm5-sum] | | [runZero Verifier ARM v6 32-bit][linux-arm6-bin]| [pgp signature][linux-arm6-asc]| [sha-256][linux-arm6-sum] | | [runZero Verifier ARM v7 32-bit][linux-arm7-bin]| [pgp signature][linux-arm7-asc]| [sha-256][linux-arm7-sum] | | [runZero Verifier ARM 64-bit (aarch64)][linux-arm64-bin]| [pgp signature][linux-arm64-asc]| [sha-256][linux-arm64-sum] | | [runZero Verifier PPC 64-bit Little Endian][linux-ppc64le-bin]| [pgp signature][linux-ppc64le-asc]| [sha-256][linux-ppc64le-sum] | | [runZero Verifier MIPS 32-bit Big Endian][linux-mips-bin]| [pgp signature][linux-mips-asc]| [sha-256][linux-mips-sum] | | [runZero Verifier MIPS 32-bit Little Endian][linux-mipsle-bin]| [pgp signature][linux-mipsle-asc]| [sha-256][linux-mipsle-sum] | | [runZero Verifier MIPS 64-bit Big Endian][linux-mips64-bin]| [pgp signature][linux-mips64-asc]| [sha-256][linux-mips64-sum] | | [runZero Verifier MIPS 64-bit Little Endian][linux-mips64le-bin]| [pgp signature][linux-mips64le-asc]| [sha-256][linux-mips64le-sum] | | [runZero Verifier S390X][linux-s390x-bin]| [pgp signature][linux-s390x-asc]| [sha-256][linux-s390x-sum] | ### MacOS {#binary-verification-macos} | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier x86 64-bit][darwin-amd64-bin]| [pgp signature][darwin-amd64-asc]| [sha-256][darwin-amd64-sum] | | [runZero Verifier ARM 64-bit][darwin-arm64-bin]| [pgp signature][darwin-arm64-asc]| [sha-256][darwin-arm64-sum] | ### BSD Variants {#binary-verification-bsd-variants} #### FreeBSD | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier x86 64-bit][freebsd-amd64-bin]| [pgp signature][freebsd-amd64-asc]| [sha-256][freebsd-amd64-sum] | | [runZero Verifier x86 32-bit][freebsd-386-bin]| [pgp signature][freebsd-386-asc]| [sha-256][freebsd-386-sum] | | [runZero Verifier ARM v6 32-bit][freebsd-arm6-bin]| [pgp signature][freebsd-arm6-asc]| [sha-256][freebsd-arm6-sum] | | [runZero Verifier ARM v7 32-bit][freebsd-arm7-bin]| [pgp signature][freebsd-arm7-asc]| [sha-256][freebsd-arm7-sum] | #### NetBSD | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier x86 64-bit][netbsd-amd64-bin]| [pgp signature][netbsd-amd64-asc]| [sha-256][netbsd-amd64-sum] | | [runZero Verifier x86 32-bit][netbsd-386-bin]| [pgp signature][netbsd-386-asc]| [sha-256][netbsd-386-sum] | | [runZero Verifier ARM v5 32-bit][netbsd-arm5-bin]| [pgp signature][netbsd-arm5-asc]| [sha-256][netbsd-arm5-sum] | | [runZero Verifier ARM v6 32-bit][netbsd-arm6-bin]| [pgp signature][netbsd-arm6-asc]| [sha-256][netbsd-arm6-sum] | | [runZero Verifier ARM v7 32-bit][netbsd-arm7-bin]| [pgp signature][netbsd-arm7-asc]| [sha-256][netbsd-arm7-sum] | #### Dragonfly | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier 64-bit][dragonfly-amd64-bin]| [pgp signature][dragonfly-amd64-asc]| [sha-256][dragonfly-amd64-sum] | #### OpenBSD | Build | PGP sig | SHA hash | |-------|---------|----------| | [runZero Verifier 64-bit][openbsd-amd64-bin]| [pgp signature][openbsd-amd64-asc]| [sha-256][openbsd-amd64-sum] | [windows-amd64-exe]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-amd64.exe [windows-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-amd64.exe.asc [windows-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-amd64.exe.sum [windows-386-exe]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-386.exe [windows-386-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-386.exe.asc [windows-386-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-windows-386.exe.sum [linux-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-amd64.bin [linux-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-amd64.bin.asc [linux-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-amd64.bin.sum [linux-386-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-386.bin [linux-386-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-386.bin.asc [linux-386-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-386.bin.sum [linux-arm5-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm5.bin [linux-arm5-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm5.bin.asc [linux-arm5-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm5.bin.sum [linux-arm6-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm6.bin [linux-arm6-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm6.bin.asc [linux-arm6-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm6.bin.sum [linux-arm7-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm7.bin [linux-arm7-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm7.bin.asc [linux-arm7-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm7.bin.sum [linux-arm64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm64.bin [linux-arm64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm64.bin.asc [linux-arm64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-arm64.bin.sum [linux-ppc64le-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-ppc64le.bin [linux-ppc64le-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-ppc64le.bin.asc [linux-ppc64le-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-ppc64le.bin.sum [linux-mips-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips.bin [linux-mips-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips.bin.asc [linux-mips-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips.bin.sum [linux-mipsle-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mipsle.bin [linux-mipsle-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mipsle.bin.asc [linux-mipsle-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mipsle.bin.sum [linux-mips64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64.bin [linux-mips64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64.bin.asc [linux-mips64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64.bin.sum [linux-mips64le-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64le.bin [linux-mips64le-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64le.bin.asc [linux-mips64le-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-mips64le.bin.sum [linux-s390x-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-s390x.bin [linux-s390x-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-s390x.bin.asc [linux-s390x-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-linux-s390x.bin.sum [darwin-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-amd64.bin [darwin-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-amd64.bin.asc [darwin-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-amd64.bin.sum [darwin-arm64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-arm64.bin [darwin-arm64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-arm64.bin.asc [darwin-arm64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-darwin-arm64.bin.sum [freebsd-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-amd64.bin [freebsd-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-amd64.bin.asc [freebsd-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-amd64.bin.sum [freebsd-386-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-386.bin [freebsd-386-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-386.bin.asc [freebsd-386-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-386.bin.sum [freebsd-arm6-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm6.bin [freebsd-arm6-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm6.bin.asc [freebsd-arm6-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm6.bin.sum [freebsd-arm7-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm7.bin [freebsd-arm7-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm7.bin.asc [freebsd-arm7-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-freebsd-arm7.bin.sum [netbsd-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-amd64.bin [netbsd-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-amd64.bin.asc [netbsd-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-amd64.bin.sum [netbsd-386-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-386.bin [netbsd-386-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-386.bin.asc [netbsd-386-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-386.bin.sum [netbsd-arm5-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm5.bin [netbsd-arm5-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm5.bin.asc [netbsd-arm5-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm5.bin.sum [netbsd-arm6-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm6.bin [netbsd-arm6-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm6.bin.asc [netbsd-arm6-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm6.bin.sum [netbsd-arm7-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm7.bin [netbsd-arm7-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm7.bin.asc [netbsd-arm7-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-netbsd-arm7.bin.sum [dragonfly-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-dragonfly-amd64.bin [dragonfly-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-dragonfly-amd64.bin.asc [dragonfly-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-dragonfly-amd64.bin.sum [openbsd-amd64-bin]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-openbsd-amd64.bin [openbsd-amd64-asc]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-openbsd-amd64.bin.asc [openbsd-amd64-sum]: https://public.runzero.com/builds/verifier/runzero-verifier-3.1.0-openbsd-amd64.bin.sum --- docs/deployment-plan.md --- title: "Full-scale deployment" --- As you get started with runZero, we recommend kicking off with our standard ((deployment plan)) and adding tasks as needed. The standard deployment plan is broken out into six stages which will help you plan out your requirements, execute the deployment, and optimize your environment based on runZero's best practices. ## 1. Identify key success outcomes **Total attack surface visibility** - [Active discovery on all internal assets](https://help.runzero.com/docs/use-case-library/#use-case-library-active-discovery) - [Active discovery on all externally facing assets](https://help.runzero.com/docs/use-case-library/#use-case-library-active-external) - [Passive discovery and enrichment in key network segments](https://help.runzero.com/docs/use-case-library/#use-case-library-passive-discovery) - [Integrate with all cloud providers and other relevant data sources](https://help.runzero.com/docs/use-case-library/#use-case-library-cloud-integration) **Additional Resources** - [Overview](https://help.runzero.com/docs/use-case-library/#use-case-library-visibility) - [RFC1918 coverage playbook](https://help.runzero.com/docs/playbooks/achieving-rfc1918-coverage/) - [Scanning OT playbook](https://help.runzero.com/docs/playbooks/scanning-ot-networks/) **Full-spectrum exposure detection** - [Rapid Response findings and asset-level pivoting](https://help.runzero.com/docs/use-case-library/#use-case-library-rapid-response-pivot) - [Network misconfiguration findings and control coverage gaps](https://help.runzero.com/docs/use-case-library/#use-case-library-network-gaps) - [Vulnerability enrichment and inside-out findings](https://help.runzero.com/docs/use-case-library/#use-case-library-enriched-findings) **Additional Resources** - [Overview](https://help.runzero.com/docs/use-case-library/#use-case-library-full-spectrum) - [Rapid Response blog](https://www.runzero.com/blog/rapid-response/) - [Gaps in EDR playbook](https://help.runzero.com/docs/playbooks/finding-gaps-in-endpoint-protection/) - [Gaps in VM playbook](https://help.runzero.com/docs/playbooks/finding-gaps-in-vuln-scanning/) **Risk prioritization and insights** - [Custom dashboards](https://help.runzero.com/docs/use-case-library/#use-case-library-custom-dashboards) - [Rules and alerts](https://help.runzero.com/docs/use-case-library/#use-case-library-rules-alerts) - [Setting asset criticality and ownership](https://help.runzero.com/docs/use-case-library/#use-case-library-asset-context) **Additional Resources** - [Overview](https://help.runzero.com/docs/use-case-library/#use-case-library-risk-insights) - [Custom Dashboards documentation](https://help.runzero.com/docs/dashboard/) - [Alerting playbook](https://help.runzero.com/docs/playbooks/alerting-on-queries/) **Compliance, Reporting, and KPIs** - [Comply with asset inventory and discovery requirements of relevant frameworks](https://help.runzero.com/docs/use-case-library/#use-case-library-asset-inventory) - [Comply with secure configuration requirements of relevant frameworks](https://help.runzero.com/docs/use-case-library/#use-case-library-secure-config) - [Comply with malware protection requirements of relevant frameworks](https://help.runzero.com/docs/use-case-library/#use-case-library-malware-protection) - [Comply with vulnerability management requirements of relevant frameworks](https://help.runzero.com/docs/use-case-library/#use-case-library-vuln-management) **Additional Resources** - [Overview](https://help.runzero.com/docs/use-case-library/#use-case-library-full-spectrum) - [Compliance alignment documentation](https://help.runzero.com/docs/compliance/overview/) - [NYDFS dashboard playbook](https://help.runzero.com/docs/playbooks/nydfs-compliance/) ## 2. ((Planning|planning)) your deployment This first set of tasks will help your team identify target results, get ahead of potential blockers, and help you avoid misconfigurations within runZero. ### Tasks - Identify key organizational stakeholders - Administrator(s) - who will be setting up runZero? - Integration owner(s) - who will provide credentials for each integration? - All users take the [runZero 101 training](https://www.runzero.com/docs/training/) - Administrators take the [runZero 201 training](https://www.runzero.com/docs/training-201) - Determine whether self-hosting is required ([docs](self-hosting.md) | [video](https://www.loom.com/share/965ecdeb34a6431f9c9f48104d0a2753)) - Determine if you will use SSO or local accounts for user access. - If SSO, you will want to start any internal processes for getting the [runZero app created](https://help.runzero.com/docs/implementing-sso/) in your provider. - Identify known networks and subnets for discovery and other inventory sources. ([docs](sample-networks.md) | [video](https://www.loom.com/share/b218e5b64d424a72b5973ffe8c582b19)) - If available, prepare [CSV files](https://help.runzero.com/docs/sites/#importing-subnets) for bulk importing subnets. - Firewalls should also be configured to allow the Explorer IPs to scan the entire network on all ports. - Define organizations based on RBAC requirements, including configuring organization-level data retention and expiration thresholds ([docs](organizations.md) | [video](https://www.loom.com/share/8f28a680af2e4c47973a7082869036af)). - Determine [Explorer](installing-an-explorer.md) deployment location(s). - [Explorer Groups](https://help.runzero.com/docs/managing-explorers/#explorer-groups) can be used to logically combine Explorers for streamlined task scheduling. - Identify required inbound integrations, prioritizing connectors for platforms such as EDR and CSPM to get full vulnerability and misconfiguration coverage. - Familiarize the team with the runZero search to plan initial asset searches and reporting requirements. ## 3. Initial configuration {#standard-configuration} Once you have your plan in place, it's time to execute and run your initial scans. **Please note** that these configuration tasks are in a prioritized order to help you avoid having to reconfigure things down the road. ### Tasks - Deploy self-hosted console (if required) ([docs](self-hosting.md) | [video](https://www.loom.com/share/965ecdeb34a6431f9c9f48104d0a2753)) - Setup [organizations](organizations.md), ensuring expiration thresholds for stale data, integrations, and vulnerabilities are configured. - Set up [sites](sites.md), and [define subnets](https://app.arcade.software/share/ta4TUUcPz5901KJ6uy1O) for discovery ([video](https://www.loom.com/share/f73750672f534cab9426f18596a4bb3a)) - **Sites do not necessarily correspond to physical locations within runZero.** Sites are used to represent distinct networks that may have overlapping IP space - This also includes Public IP space and domains for external scanning. - Install [Explorer(s)](installing-an-explorer.md) ([video](https://www.loom.com/share/32fbc1877eb049bbaada7a0f77a72c6f)) - If planned, configure Explorer Groups to logically organize scanners for streamlined task distribution. - Define private network addresses - You can set custom Private IP ranges if you use Public IP ranges internally in [Account Settings](https://console.runzero.com/account). - Run initial scan ([docs](running-initial-scans.md) | [video](https://www.loom.com/share/b4138aad97714b789ab7dc5d3442a65b)) - [Configure credentials](scanning-credentials.md) and inbound [integration](integrations-inbound.md) connections - [Cloud inventory sources](integrations-inbound.md#cloud-and-virtualization) - [Endpoint protection](integrations-inbound.md#endpoint-protection) - [Vulnerability management](integrations-inbound.md#integrations-inbound-vm) - [Directory services](integrations-inbound.md#asset-and-identity-management) - [Custom Integrations](https://github.com/runZeroInc/runzero-custom-integrations/tree/main?tab=readme-ov-file#runzero-custom-integrations) ## 4. Review Assets and Exposures Now that you have done some initial discovery and leveraged integrations, it's time to review the results. Reviewing the results and leveraging our advanced reporting features will help you expand scan scope, prioritize risk, better understand your network, and identify key exposure issues such as misconfigurations and actively exploited vulnerabilities. ### Tasks - **Review Results and Exposure Overview** - Review the **Risk Management Dashboard** (new default dashboard) for a centralized view of risks. This dashboard provides insights, trend data, and breakdowns of assets ([docs](dashboard.md)). - Check the **Latest Rapid Response alerts** widget, which includes a carousel of the five most recent Rapid Response posts and displays matches in your inventory ([docs](em-rapid-response.md)). - Leverage the capability to create and share **multiple, custom dashboards** for different use cases or teams (e.g., Compliance or Vulnerability Management) ([docs](dashboard.md)). - Review the Asset Inventory ([docs](using-the-inventory.md)). The inventory correlates and merges assets across all data sources (scan, passive, and integrations) to provide a single source of truth. - Review the Asset Detail View, noting the consolidated view of attributes, vulnerabilities, and software ([docs](understanding-assets.md)). - **Identify and Prioritize Exposures with Findings** - Review the **Findings** section, which aggregates vulnerabilities and misconfigurations into prioritized risk categories (e.g., **Internet Exposure**, **Open Access**, **End-of-Life**, **Certificates**, **Vulnerability**, and **Best Practice Violations**) ([docs](understanding-findings.md)). - **Deep Investigation and Querying** - Identify risky assets using the Queries library ([docs](querying-your-data.md)): - Learn query syntax ([docs](search-query-syntax.md)). - Apply vulnerability records to queries (e.g., for novel internal findings) ([docs](search-query-vulnerabilities.md)). - Filter assets and services directly by their associated **Finding Code** (e.g., `finding_code:rz-finding-internet-exposed-database`) to target remediation ([docs](search-query-findings.md)). - Search for assets exposed to **Known Exploited Vulnerabilities (KEV)** lists (CISA KEV, VulnCheck) and leverage **EPSS scores** for priority assessment. - **Track Long-Term Initiatives** - **Track long-term initiatives with Goals** ([docs](goal-tracking.md)). - Utilize **Baseline Goals** to measure progress against specific inventory subsets (e.g., setting a goal to remediate all expired certificates or critical vulnerabilities in the `os_eol: - Ensure default credential and vulnerability checks are enabled on all scans. - Current coverage can be found [in this documation](em-templates.md). - Configure [asset ownership](managing-ownership.md) to streamline investigations. ## 6. Automation Now that you have optimized your scans and have analyzed your runZero data, you can automate these tasks to avoid manual effort. You can leverage this automation to run scans on a recurring basis, automate queries, and generate alerting for the team. ### Tasks - Schedule recurring scan [tasks](managing-tasks.md) and any inbound [integration tasks](integrations-inbound.md) - [Automate queries](automating-queries.md) and [configure alerts](rules-engine.md) to align with use cases ([video](https://www.loom.com/share/ab137f83d8384ea79f8c3c49f50eb0f0)) - Use rules to automate tagging and setting asset criticality ([walkthrough](https://help.runzero.com/docs/use-case-library/#use-case-library-asset-context)) - Setup alerts for [system events](https://help.runzero.com/docs/playbooks/alerting-on-system-events/) like Explorer offline and scan failures. - Configure outbound [integration](integrations-outbound.md) connections to enrich other IT and security tools - [CMDB](integrations-outbound.md#it-service-management) - [SIEM](integrations-outbound.md#detection-and-investigation) - [SOAR](integrations-outbound.md#detection-and-investigation) - **Note:** If you're utilizing a solution that runZero does not offer a standard outbound integration for at this time, be sure to review our [API documentation](leveraging-the-api.md) to learn about how to export runZero data. ## 7. Rollout As your runZero deployment comes to a close, you will want to ensure all users have gone through training and ensure anyone that would get value from runZero has access to the platform. ### Tasks - [Add users](managing-your-team.md) - Ensure all users are trained on runZero - Training and key documentation - [101 user training](https://www.runzero.com/docs/training/) - [201 administrator training](https://www.runzero.com/docs/training-201) - [Use case library](https://help.runzero.com/docs/use-case-library/) - [Search](search-query-syntax.md) - [Reporting](reviewing-results.md#reports) - [Exporting assets](exporting-asset-data.md) - [runZero playbooks](https://www.runzero.com/docs/playbooks/playbooks/) - Identify other teams interested in the asset inventory data, such as: - [Enterprise security team](https://www.loom.com/share/8ae585b714494964ab008d2df21386d4) - runZero is typically used by security teams to achieve a complete asset inventory, find gaps in their vulnerability scanning and endpoint protection, as well as discover potential vulnerabilities. - [IT Operations team](https://www.loom.com/share/741bcb1ba9ba40ba8d67d5335cfcff2c) - runZero is typically used by IT Operations teams to achieve a complete inventory of all assets across on-premise and cloud-based infrastructure. This allows the team to identify misconfigurations as well as report on assets in the environment by leveraging our searching and reporting capabilities. - [Penetration testing team](https://www.loom.com/share/7f309576b7fa445b96a5e378bbd0427f) - runZero is typically used by penetration testing teams for conducting reconnaissance both internally and externally, identifying vulnerable targets, and finding ways to get to these vulnerable targets by using our reporting and searching capabilities. ## Additional Resources {#deployment-plan-resources} Now that runZero has been deployed and users have been trained on the platform, please review some of our additional resources to help answer questions you might have as well as maximize the value of runZero: - [runZero playbooks](https://www.runzero.com/docs/playbooks/playbooks/) - [Use Case Library](https://help.runzero.com/docs/use-case-library/) - [Leveraging the API](leveraging-the-api.md) - [Glossary](glossary.md) - [runZero FAQs](troubleshooting.md) ## Getting help {#deployment-plan-getting-help} If you need assistance at any point in this process, you can [book a session with a runZero Customer Success Engineer](https://scheduler.zoom.us/d/z8gaq_36/runzero-customer-success-engineer) to discuss further. --- docs/sample-networks.md --- title: "Types of networks" --- It is often helpful to use ((network examples)) as a starting point for planning your runZero implementation. This document breaks down a few standard network types and provides potential configurations for each. With that being said, every network has nuance, so it's likely there will be some differences for your implementation. This is a basic overview of how discovery will be done using Explorers and scanners. By default, one Explorer will be deployed with the goal of running discovery on as much of the network as possible. If needed, more Explorers can be added for areas the primary Explorer cannot get to. You can also use a scanner for offline environments where there is no internet connectivity. ![runZero deployment diagram](img/deployment-diagram.svg) ## SaaS company ### Network characteristics - Flat on-premises network for offices - Multi-cloud environment - Hybrid workforce remote and in office ### Sample runZero implementation - Explorers - Corporate network Explorer that is able to get all on-premises network and cloud services private connectivity - One Explorer per VPC that isn't routable from on-premises networks - Organizations - Single organization - Sites - Primary corporate site - One site per VPC ## Large corporation ### Network characteristics - Corporate offices with many connected branches - Multiple M&A transactions happening at any given time, onboarding new offices every year - Multiple data centers for internal and externally-facing applications ### Sample runZero implementation - Explorers - Corporate network Explorer that is able to get all on-premises networks - One Explorer per site with low bandwidth or legacy firewalls, proxies, etc. - One Explorer for each M&A transaction to understand new risks and keep data segmented - Organizations - Corporate assets - One project per M&A transaction until the deal is complete and assets are merged - Sites - Primary corporate site - Potentially separate sites if there is overlapping IP space in branch offices ## Retail company ### Network characteristics - Flat on-premise network for corporate offices - Data centers - 100s of retail locations ### Sample runZero implementation - Explorers - Corporate network Explorer that is able to get all on-premise networks - One Explorer per retail location with low bandwidth or legacy firewalls, proxies, etc. - One Explorer per data center - Organizations - Single organization - Sites - Primary corporate site - One per retail site if they have overlapping IP space ## Manufacturing company ### Network characteristics - Flat on-premise network for corporate offices - OT environment is completely disconnected from the internet - Field service agents VPN in from varying locations ### Sample runZero implementation - Explorers - Corporate network Explorer that is able to get all on-premise networks - Scanners - Manufacturing plant that is not connected to the corporate networks - Organizations - Single organization - Sites - Primary corporate site - One per OT site if there is overlapping IP space ## Telecommunications company ### Network characteristics - Flat on-premise network for corporate offices - Segmented data centers - IoT devices scattered across the country - Field service agents VPN in from varying locations ### Sample runZero implementation - Explorers - Corporate network Explorer that is able to get all on-premise networks - One for each segmented lab - One for each data center - Organizations - Corporate network - Production network - One per lab - Sites - One primary site per organization ## Managed security service provider ### Network characteristics - Many customers spinning up/down in engagements - Mostly small, flat networks - Some customers have OT environments that are sensitive ### Sample runZero implementation - Explorers - One per customer - Scanners - Only needed for customers with offline networks - Organizations - Project per customer initially - Promote project to organization for long-term use - Sites - One per customer but potentially multiple if a customer has overlapping IP space ## Academic organization ### Network characteristics - Many buildings/networks spread around the campus with varying connectivity - Multiple data centers managed by different departments - Multiple labs for research and development that are disconnected from the rest of the network and the internet ### Sample runZero implementation - Explorers - Main network Explorer that is able to get all on-premise networks - One Explorer per building with low bandwidth or legacy firewalls, proxies, etc - One Explorer per data center - Scanners - One for each disconnected lab - Organizations - Main assets - One for each lab - Sites - One primary per organization but potentially multiple if buildings have overlapping IP space --- docs/use-case-library.md --- title: Use case library --- ## Appendix - [Total attack surface visibility](#use-case-library-visibility) - [Active discovery on all internal assets](#use-case-library-active-discovery) - [Active discovery on all externally facing assets](#use-case-library-active-external) - [Passive discovery and enrichment in key network segments](#use-case-library-passive-discovery) - [Integrate with all cloud providers and other relevant data sources](#use-case-library-cloud-integration) - [Full-spectrum exposure detection](#use-case-library-full-spectrum) - [Rapid Response findings and asset-level pivoting](#use-case-library-rapid-response-pivot) - [Network misconfiguration findings and control coverage gaps](#use-case-library-network-gaps) - [Vulnerability enrichment and inside-out findings](#use-case-library-enriched-findings) - [Risk prioritization and insights](#use-case-library-risk-insights) - [Custom dashboards](#use-case-library-custom-dashboards) - [Rules and alerts](#use-case-library-rules-alerts) - [Setting asset criticality and ownership](#use-case-library-asset-context) - [Compliance, Reporting, and KPIs](#use-case-library-compliance) - [Comply with asset inventory and discovery requirements of relevant frameworks](#use-case-library-asset-inventory) - [Comply with secure configuration requirements of relevant frameworks](#use-case-library-secure-config) - [Comply with malware protection requirements of relevant frameworks](#use-case-library-malware-protection) - [Comply with vulnerability management requirements of relevant frameworks](#use-case-library-vuln-management) ## Total attack surface visibility {#use-case-library-visibility} Achieving complete visibility is essential for understanding and managing your organization's attack surface. This encompasses internal and external assets, cloud amd security tooling integrations, and passive discovery methods to ensure comprehensive oversight and proactive threat mitigation. ### Active discovery on all internal assets {#use-case-library-active-discovery} This use case focuses on identifying all internal assets within defined network boundaries. It ensures organizations can actively monitor their managed networks to maintain up-to-date inventory. #### Steps: 1. Define networks of interest/managed networks/known subnets. 2. Configure Organization(s) and Site(s). 3. Install Explorer(s). 4. Configure scan(s). 5. Review inventory to verify connectivity and fingerprinting looks good. ### Active discovery on all externally facing assets {#use-case-library-active-external} Gain visibility into external assets, such as domains and IP ranges, that represent your public-facing footprint. This approach ensures you can proactively address vulnerabilities in your external attack surface. By monitoring external-facing assets, organizations can identify vulnerabilities and misconfigurations before they are exploited. Continuous scanning and updates keep your external inventory current and secure. #### Steps: 1. Define external ranges, domains, and subdomains. 2. Set external ranges, domains, subdomains, and ASN4 numbers within scan scope. 3. Run scan using runZero hosted zones. 4. Review inventory to verify findings. ### Passive discovery and enrichment in key network segments {#use-case-library-passive-discovery} Identify assets and gain insights without active scanning by leveraging network TAPs or SPAN ports. This ensures continuous monitoring with minimal disruption to network operations. Passive discovery complements active methods by observing traffic patterns and enriching data without interrupting critical operations. This approach is ideal for sensitive network segments. #### Steps: 1. Set up a network TAP or a SPAN port/leverage already existing network TAP or SPAN. 2. Put explorer on network TAP or host sitting on the SPAN port. 3. Configure the explorer to listen over relevant interfaces, set scan scope, set and forget. ### Integrate with all cloud providers and other relevant data sources {#use-case-library-cloud-integration} Seamlessly connect with cloud providers and other data sources to ensure complete visibility across hybrid environments. Simplify asset management by unifying data under one platform. Cloud integration enables real-time visibility into assets spread across various platforms. It reduces manual effort and enhances data consistency by leveraging automated updates from connected sources. #### Steps: 1. Configure integrations with EDR, MDM, directory services, cloud solutions, and vulnerability management platforms. 2. Ensure on-prem solutions have an explorer to run successfully, whereas cloud solutions do not require an explorer. ## Full-spectrum exposure detection {#use-case-library-full-spectrum} Gain comprehensive visibility across your environment by correlating Rapid Response insights, asset-level context, control coverage gaps, and enriched vulnerability data. This layered approach enables faster detection, better prioritization, and more targeted response efforts. ### Rapid Response findings and asset-level pivoting {#use-case-library-rapid-response-pivot} Quickly investigate Rapid Response findings by moving from high-level dashboards to individual assets. This seamless workflow brings together threat intelligence, exposure history, and asset impact for fast and actionable insights. #### Steps: 1. Review the [Risk Dashboard](https://console.runzero.com/dashboards/6151aaec-d99b-45f4-8279-8333f1dfaff1). 2. Review the [Rapid Response](https://www.runzero.com/blog/rapid-response/) blog to see past examples. 3. Open [Rapid Response queries](https://console.runzero.com/queries?search=category%3A%22Rapid%20Response%22) to examine historical trends. ### Network misconfiguration findings and control coverage gaps {#use-case-library-network-gaps} Identify network misconfigurations and highlight security control gaps—like missing EDR or VM coverage—by using targeted queries and contextual inventory views. This helps prioritize risk reduction efforts based on actual gaps in defense. #### Steps: 1. Review [sample network misconfiguration](https://console.runzero.com/findings?search=name%3Aauth) findings. 2. View [all assets with an associated finding](https://console.runzero.com/inventory?search=finding%3At). 3. View [assets missing EDR coverage](https://console.runzero.com/inventory?search=finding%3At%20not%20%28source%3Acrowdstrike%20or%20source%3Asentinelone%20or%20source%3Ams365defender%29%20%28type%3Aserver%20or%20type%3Adesktop%20or%20type%3Alaptop%29). ### Vulnerability enrichment and inside-out findings {#use-case-library-enriched-findings} Enhance your vulnerability management process with enriched context such as KEV status, exposure points, and related asset attributes. Combine these filters with reports like network bridges to identify exploitable attack paths. #### Steps: 1. Review [KEV (Known Exploited Vulnerabilities)](https://console.runzero.com/findings?search=name%3Aknown) findings. 2. View [assets with a finding and vulnerability on the KEV](https://console.runzero.com/inventory?search=finding%3At%20kev%3At%20has_public_v4%3At). 3. View [network bridges report](https://console.runzero.com/reports/analysis/bridges?mask=24&filter=finding:t) filtered to only assets with an associated finding. ## Risk prioritization and insights {#use-case-library-risk-insights} Prioritize what matters most by aligning dashboards, alerts, and asset context to risk. Use customizable workflows and real-time metrics to drive better decision-making and reduce noise. ### Custom dashboards for dynamic visibility {#use-case-library-custom-dashboards} Build dashboards tailored to your environment and objectives. Combine stock widgets, saved queries, and custom metrics to track what matters and highlight key trends. #### Steps: 1. Go [the runZero home page](https://console.runzero.com/) to create a new dashboard. 2. Click Widgets to add your selection. ### Rules and alerts for automated monitoring {#use-case-library-rules-alerts} Turn searches into alerts by creating rules that notify your team of meaningful changes. Use templates and channels to streamline alert creation and delivery. #### Steps: 1. Create [channel](https://console.runzero.com/alerts/channels/create) or destination for your notifications. 2. Create [template](https://console.runzero.com/alerts/templates/create) for you payload. - See samples [alert templates](docs/creating-alert-templates.md). 3. Go to [create rule](https://console.runzero.com/alerts/rules). 4. Finalize logic, review, and save. ### Asset criticality, ownership, and search filters {#use-case-library-asset-context} Improve search relevance and response precision by tagging assets with criticality and ownership metadata. These values also drive automated rule actions. #### Steps: 1. Search for specific assets in the inventory view. 2. Update asset criticality or ownership directly from the inventory. 3. Use rule with _Modify assets_ Action to update the desired values. ## Compliance, Reporting, and KPIs {#use-case-library-compliance} Adhering to compliance standards requires accurate asset tracking, secure configurations, and effective vulnerability management. runZero simplifies these processes to help organizations meet regulatory demands. ### Comply with asset inventory and discovery requirements of relevant frameworks {#use-case-library-asset-inventory} Maintain compliance with industry standards by ensuring accurate and comprehensive asset discovery. Demonstrate adherence through detailed inventory and reporting. Comprehensive inventory management helps organizations satisfy regulatory audits. Combining active, passive, and integration-based discovery methods ensures no assets are overlooked. #### Steps: 1. Review documentation mapping runZero to compliance frameworks. 2. Review active, passive, and integrations options. 3. Use the task history to see when scans or integrations ran. 4. Display inventory for real-time compliance visibility. ### Comply with secure configuration requirements of relevant frameworks {#use-case-library-secure-config} Meet secure configuration standards by identifying and addressing insecure protocols or configurations. Ensure alignment with regulatory requirements. Secure configurations are critical for mitigating risks associated with legacy protocols and insecure settings. Automation tools enhance efficiency in identifying and remediating issues. #### Steps: 1. Review documentation mapping runZero to compliance frameworks. 2. Use search for insecure protocols like FTP, TFTP, Telnet, and HTTP. 3. Save searches for tracking and add to the dashboard for reporting. ### Comply with malware protection requirements of relevant frameworks {#use-case-library-malware-protection} Integrate with Endpoint Detection and Response (EDR) solutions to ensure compliance with malware protection standards. Identify and address gaps in protection. Effective malware protection depends on real-time monitoring and quick response. Comprehensive integration options streamline the detection and resolution of gaps. #### Steps: 1. Review documentation mapping runZero to compliance frameworks. 2. Review EDR integrations and options for custom integration. 3. Search for gaps in EDR and alert on newly found gaps. ### Comply with vulnerability management requirements of relevant frameworks {#use-case-library-vuln-management} Leverage integrations and inventory tools to meet vulnerability management requirements. Track and address vulnerabilities effectively. Meeting vulnerability management requirements involves continuous monitoring, prioritization, and remediation. Automated tools provide actionable insights to streamline this process. #### Steps: 1. Review documentation mapping runZero to compliance frameworks. 2. Search for gaps in vulnerability scanning. 3. Use vulnerability inventory with KEV/EPSS enrichments for enhanced insights. () --- docs/training.md --- title: runZero 101 training --- This training introduces the core components of the runZero platform. It provides the foundational concepts that help you understand how runZero gathers and structures asset data, how to explore the environment, and how to begin identifying risks and trends. Each section includes an accompanying walkthrough and links to deeper documentation. [runZero 201](training-201.md) covers advanced workflows, automation, and deployment planning. ## Platform overview {#platform-overview} Before using inventories, findings, reporting views, or dashboards, it’s important to understand the core concepts that shape how runZero organizes and processes data. This section provides short, conceptual introductions to: - How runZero structures data using **Organizations** and **Sites** - How runZero collects and updates data using **Tasks** - How runZero builds unified asset records using **Sources** and merging behavior These concepts provide the mental model for everything else in the console. ### Organizations and Sites {#platform-orgs-sites} runZero uses two levels of structure to organize data and control visibility. #### Organizations {#platform-organizations} Organizations define data segmentation and RBAC boundaries. Each Organization maintains its own: - Assets - Findings - Dashboards - Queries - Integrations - Tasks Use Organizations when you need clear separation between environments (e.g., subsidiaries, departments, or multi-tenant structures). #### Sites {#platform-sites} Sites represent network structure. A Site corresponds to one or more IP ranges and is used for: - Assigning assets to a network location - Generating scan scopes - Structuring reporting - Improving segmentation in queries and dashboards Sites do **not** define access control. They provide context for how assets are grouped and discovered. **Learn more:** - [Organizations](organizations.md) - [Sites](sites.md) ### Tasks {#platform-tasks} Tasks are how data enters runZero. Every collection action in the platform is performed by a Task. #### Types of Tasks {#platform-task-types} - **Scan tasks** (active discovery) - **Integration tasks** (data pulled from external systems) - **Monitor tasks** (passive discovery) Each Task includes: - Status (success, partial, failure) - Start and end timestamps - Asset and service counts - Link to the associated Explorer (if applicable) Task results drive inventory freshness, dashboard updates, findings, and search counts. If data appears out of date, the Task history is the first place to check. **Learn more:** - [Managing tasks](managing-tasks.md) - [Discovering assets](discovering-assets.md) ### Sources and merging {#platform-sources-merging} runZero unifies asset data from multiple origins—scans, integrations, and passive monitoring. Each asset may contain attributes from multiple **sources**, and runZero automatically merges them into a single asset record. #### Key concepts {#platform-sources-key-concepts} - Source indicators show where an attribute came from - Conflicting values are resolved using a deterministic merge strategy - Merging reduces duplicates and consolidates metadata - `source:` filters allow quick pivoting by origin system - Asset details show a breakdown of attributes by source This merging process enables runZero to act as a single source of truth across your IT, OT, cloud, and security stack. **Learn more:** - [Understanding assets](understanding-assets.md) - [Fingerprinting and merging](fingerprinting.md) ## Inventory views {#inventory-views} This section introduces the primary inventory views in runZero and explains how to navigate and interpret them. These views provide the foundation for exploring your environment. ### Asset Inventory {#inventory-asset} The Asset Inventory shows every asset known to runZero across all sources. Common tasks include: - Filtering by IP, hostname, OS, software, or exposure - Identifying device types across IT, OT, IoT, and cloud - Reviewing asset context such as criticality, ownership, tags, and findings - Exporting subsets of data for analysis or reporting **Learn more:** - [Using the inventory](using-the-inventory.md) ### Asset detail {#inventory-asset-detail} The Asset detail page provides a complete, merged view of all metadata for an asset Key values found on the details page include: - Attributes from each source - Services - Vulnerabilities and findings - Certificates - Ownership and criticality - Historical changes This is the primary investigative view when troubleshooting or reviewing an asset. **Learn more:** - [Understanding assets](understanding-assets.md) - [Managing ownership](managing-ownership.md) - [Asset risk and criticality](asset-risk-and-criticality.md) ### Service Inventory {#inventory-service} The Service Inventory provides visibility into every network service discovered through scanning or imported through integrations. It helps identify: - Exposed services - Protocol-level misconfigurations - Public-facing services - Administrative or remote access interfaces **Learn more:** - [Service search examples](search-query-services.md) ### Vulnerability & Software Inventories {#inventory-vuln-sw} These views consolidate vulnerability and software metadata across all sources. #### Vulnerability Inventory {#inventory-vuln} Shows vulnerabilities identified through: - Native findings - Enriched vulnerability data from integrations - KEV correlation (CISA KEV and VulnCheck) #### Software Inventory {#inventory-software} Shows discovered software packages and versions, enabling: - License tracking - Version drift analysis - Identifying outdated or insecure software **Learn more:** - [Understanding findings](understanding-findings.md) - [Vulnerability search examples](search-query-vulnerabilities.md) ## Findings {#findings-overview} Findings identify exposures, misconfigurations, vulnerabilities, and security control gaps. This section introduces how Findings work and how to explore them. ### Findings overview {#findings-main} Findings combine multiple signals—including scan data, integration data, KEV enrichment, and novel runZero detections—to provide a high-level view of environmental risk. Common categories include: - Vulnerabilities - Administrative access exposures - Network misconfigurations - Missing security controls (e.g., EDR, MDM, VM) - runZero novel findings (e.g., Widely Shared Private Keys) **Learn more:** - [Understanding findings](understanding-findings.md) ### Findings detail {#findings-detail} The Findings Detail view shows: - Description and severity - Evidence from affected assets - Remediation guidance - Links to pivot into Asset Inventory, Service Inventory, or Vulnerabilities ### Vulnerability detail {#findings-vuln-detail} The Vulnerability Detail page merges CVE data from all sources and includes: - CVSS scores and vectors - CISA KEV and VulnCheck KEV metadata - Affected assets and services - Consolidated descriptions and references ## Reporting {#reporting-overview} Reporting views help visualize your network layout, segment boundaries, subnet coverage, and topology. ### Switch Topology & Unmapped MACs reports {#reporting-topology} Switch Topology shows: - Switches and physical connections - Link relationships - Interface details Unmapped MACs highlight assets communicating on the network but not mapped to switch ports. **Learn more:** - [Switch topology report](switch-topology-report.md) ### Subnet Utilization & RFC1918 Coverage reports {#reporting-rfc1918} These reports help validate scanning completeness and asset density across subnets: - Percentage of IP space scanned - Allocated vs. active subnets - Hinted assets discovered through passive observations **Learn more:** - [Coverage reports](coverage-reports.md) ### Network Bridges & Asset Route Pathing reports {#reporting-bridges} These views help understand blast radius and segmentation: - **Network Bridges:** Visualize internal and external network connections - **Route Pathing:** Understand traversal paths between assets **Learn more:** - [Understanding network segmentation](understanding-network-segmentation.md) - [Asset route pathing report](asset-route-pathing-report.md) ### Custom Asset & Service Attribute reports {#reporting-custom} These reports allow analysis of: - Common OS families - Hardware vendor distribution - Service protocols - Certificate attributes - Custom attributes from integrations ## Search, Goals, and Custom Dashboards {#search-goals-dashboards} Search powers nearly every workflow in runZero. Goals and dashboards allow you to track trends over time and visualize key results. ### Query Library {#search-query-library} The Query Library stores saved searches for: - Rapid Response - Gaps in controls - Common exposure profiles - Custom organization searches Saved searches power: - Dashboards - Goals - Alerts - Automation via rules **Learn more:** - [Querying your data](querying-your-data.md) - [Search syntax](search-query-syntax.md) ### Baseline Goals {#search-goals} Goals measure progress toward internal or external requirements. Examples include: - Reducing assets missing EDR - Lowering the count of public-facing services - Tracking vulnerability remediation progress **Learn more:** - [Goal tracking](goal-tracking.md) ### Custom Dashboards {#dashboards} Dashboards consolidate searches and metrics. You can: - Build dashboards per team or use case - Add widgets from stock or custom searches - Share dashboards across Organizations - Recalculate on demand **Learn more:** - [Dashboard documentation](dashboard.md) ### Custom Dashboard Widgets {#dashboard-widgets} Widgets allow visualization through: - Counts - Trend lines - Goal overviews Widgets can be created from any saved search. ## Next Steps {#training-next-steps} Once you’ve completed this 101 training, continue with: - **[runZero 201 Training](training-201.md)** Builds on the foundations covered here with deeper dives into deployment planning, Explorer strategies, advanced search techniques, automation, and workflow optimization. Ideal for admins or operators responsible for maintaining runZero at scale. - **[Use Case Library](use-case-library.md)** A collection of short, outcome-focused guides showing how to solve specific problems using runZero. Each use case includes example searches, Arcades, and recommended workflows to apply the platform to real scenarios. - **[Playbooks](playbooks/playbooks.md)** Step-by-step procedures for executing repeatable security and IT tasks, such as achieving full RFC1918 coverage, identifying gaps in endpoint protection, or preparing for compliance audits. Designed to turn best practices into actionable workflows. This training provides the foundation needed to operate runZero effectively, investigate assets, interpret findings, and begin measuring and improving your security posture. --- docs/training-201.md --- title: runZero 201 training --- ## Prerequisites Prior to starting this ((training)), we have two recommendations: 1. **Superuser access** to a runZero account. This can be a corporate account with a paid license, or you can use a personal email to create a community account which will make you the superuser. 2. **Completion of the** [runZero 101 training](https://help.runzero.com/docs/training/) is also recommended so that you understand the context behind all of the administrative actions you will learn about in this training. ### Introduction to the training This video provides a brief introduction to what you will learn in this training. ## Self-hosting {#201selfhosting} runZero allows for [self-hosting](self-hosting.md). The self-hosted version of runZero is identical to the SaaS version outside of a couple edge cases like the runZero Hosted explorers not being available. Self-hosting must be explicitly enabled on your runZero account. Please contact your runZero sales representative for further information.
Note
You can skip this section if you are using the SaaS console for runZero.
### Deployment planning The demo below shows you a walkthrough of the deployment planning section. The written form can be found below the demo. 1. **Hardware requirements** - these depend on the asset count. Recommended production system requirements: - 12 CPU Cores at 2 GHz or faster - 1TB of local disk storage - 128 GB of RAM Minimum production system requirements: - 4 CPU Cores at 2 GHz or faster - 100 GB of local disk storage - 32 GB of RAM (more for large sites) Minimum testing system requirements: - 2 CPU Cores at 2 GHz or faster - 20 GB of local disk storage - 16 GB of RAM (more for large sites) 2. **Operating system** - self-hosting runZero supports most flavors of Linux. - Ubuntu 18.04 and newer running on x86_64 - Red Hat Enterprise Linux 7.x and newer running on x86_64 - CentOS Linux 7.x and newer running on x86_64 - Oracle Linux 7.x and newer running on x86_64 - 8.x must be 8.4+ with UEK 5.4+ or kernel 4.18+ - 7.x must be 7.9+ with UEK 5.4+ or kernel 3.10+ - Debian Linux 9.x and newer running on x86_64 3. **Connectivity** For a standard deployment, you will need the server to have outbound access on TCP port 443 for HTTP over TLS to the runZero domains and IPs for installation and updates.The specific IP addresses and hostnames depend on your deployment model and region and can be found below. #### United States {#training-us} The console hostname is `console.runzero.com`. IPv4 * 13.248.161.247 * 76.223.34.198 IPv6 * 2600:9000:a415:cd87:fbe5:476a:3533:69f2 * 2600:9000:a716:ee91:85f9:3c9:48c9:59b9 #### Germany {#training-de} The console hostname is `console-eu.runzero.com`. IPv4 * 15.197.131.232 * 3.33.248.90 IPv6 * 2600:9000:a603:e925:542d:6d40:6897:bc3a * 2600:9000:a70e:635f:71bd:bb0a:8e43:9466 4. **Offline mode** - you can deploy in [offline mode](self-hosting.md#offline-mode) as well, but updates will be a manual process. ### Setup The demo below shows you a walkthrough of the self-hosted setup section. The written form can be found below the demo. 1. **Installation** - The runZero installation is a single command that can be obtained from your runZero SaaS console. - This can be obtained as [a download from the console](https://console.runzero.com/deploy/download/platform) assuming you have it enabled in your account. - Additional details for this part of the setup can be found in [our online documentation pages](self-hosting.md#step-1-download-and-run-the-installer). 2. **Post installation** - Once the console is installed, you can create your admin user and login with this command `runzeroctl initial ` - Additional details for this part of the setup can be found in [our online documentation pages](self-hosting.md#step-3-initialize-the-admin-user). 3. **Using your own PostgreSQL database** - You can use separate servers for the console and database if you’d like to scale your workload horizontally. - Additional details for this part of the setup can be found in [our online documentation pages](self-hosting.md#manual-database-install). 4. **Advanced configuration** Here are a few other common customization options: - Email Server (for Alerting and User Invites) - TLS Certificates - Hostname - Additional details for this part of the setup can be found in [our online documentation pages](self-hosting.md#advanced-configuration). 5. **Logging** - Self-hosted runZero logs to the standard `journalctl`` to simplify capturing data. - You can view logs with this sample command `journalctl --unit=runzero-console --since=-1hour --reverse` ### Using runzeroctl {#201usingrunzeroctrl} Most actions you need such as starting or stopping the service, creating the initial user, etc can be done with the runzeroctl CLI. Here are few common commands used: - Restart the service - `runzeroctl restart` - Update the platform and scanners - `runzeroctl update [--force]` - Reset user password and MFA - `runzeroctl user reset ` - Additional details for this part of the setup can be found in [our online documentation pages](self-hosting.md#cli-service-management). ## Initial configurations This section will cover the basics for getting runZero configured. It will cover user management and data architecture. ### Users {#201users} The demo below shows you a walkthrough of the users section. The written form can be found below the demo. User management is all done under the Your team tab in the left navigation. You will see 5 sub options: 1. **Users** - shows all users in the current client account. 2. **Restricted** - lists users who only have access to a single organization. 3. **Your Organization Name** - lists users who have access to the organization your are currently using. 4. **External** - lists users who’s authentication happens on a different runZero client account but have access to at least one organization in your current account. 5. **Groups** - lists the user groups available. The groups define the access and permissions users have within each organization. Adding users: 1. **Depending on the user type** you’d like to create, you click into the tab of that user type ex. External, Restricted, etc. 2. **You will see two options** on the top right to Invite users and Import users. - Invite - you will provide an email, set the access level, and optionally edit the email invitation. - Import - runZero allows a CSV import to bulk create users. First name, Last name, and Email are required. Permissions are optional, and users will default to the least permissions possible if not provided. 3. **SSO** - you can manage SSO through the first Users tab. Click _SSO Settings_ to do this. - **SSO modes** 1. Disabled - SSO not in use. 2. Allowed - SSO and local accounts can both be used. 3. Required - SSO accounts only. Local accounts are not allowed. - **Service provider settings** 1. runZero provides the necessary information to create the runZero application in your service provider if you click [Service Provider Information](https://console.runzero.com/team/sso/sp/). 2. You can read [more information about implementing SSO](implementing-sso.md) for specific service provider documentation. - **SSO group mappings** 1. You can create SSO group mappings into runZero to set permissions. 2. These settings will not be applied until after the next sign-out, and you can [force sign-outs](managing-sso-group-mappings.md#forcing-a-user-to-sign-out) through the console. 3. If multiple SSO group mappings match, the highest privilege mapping will take precedence.
Note
We generally recommend keeping a single local account for break glass situations, but support can also assist if needed.
### Organizations and Projects The demo below shows you a walkthrough of the organizations and projects section. The written form can be found below the demo. 1. **Organizations** are how RBAC is handled in runZero. If you need to segment user’s visibility into sets of assets, you should put them in different Organizations. - User permissions are also set at the Organization level, so a user could be an Admin in one, a standard User in another, and a Viewer in a third. - Every user will have an All Organizations view that allows them to search the inventories of all of the Organizations they have access to at once. 2. **Projects** are short term and meant for short term engagements. They go read-only after 30 days and automatically delete after 90 days. ### Sites {#201sites} The demo below shows you a walkthrough of the sites section. The written form can be found below the demo. 1. **Sites** are primarily meant to represent networks with overlapping IP space rather than physical locations. 2. You should use one Primary site unless you have overlapping IP space. 3. Each site will have a set of subnets associated with it which you can also apply tags to. 4. You can also [import a CSV of subnets](https://console.runzero.com/sites/import) to create your sites.
Note
Scanning the same IP addresses in different sites WILL create duplicate assets. You should not do this unless you have overlapping IP space.
## Managing tasks Tasks are how you get data into runZero. There are three primary task types: 1. Active scan 2. Passive traffic sampling 3. Integration connections In this section we will cover all of the different ways you can schedule these tasks to run. ### Explorers The demo below shows you a walkthrough of the explorers section. The written form can be found below the demo. While explorers are primarily meant for active scanning and passive traffic sampling, you can also run every integration connection from an explorer as well. #### Installation {#201installation} 1. **Recommended hardware** - Processor running at 2.0 GHz or faster - At least 16GiB of memory (8GiB for small environments) - At least 1GB of free storage space 2. **Supporting operating systems** - The explorer can be installed on macOS, and most Linux or Windows Operating Systems - You can see a [full list of supported operating systems](installing-an-explorer.md#system-requirements). 3. **Installation** - You will navigate to the [Deploy tab](https://console.runzero.com/deploy/download/explorers) in the UI to get your unique explorer download link. - Just select your OS type and follow the instructions. 4. **Verify connectivity** - Once your explorer has successfully installed, it will check in to the Console and show Online. - You can [see your explorers](https://console.runzero.com/deploy/explorers) in the console. #### Configuration {#201configuration} 1. **Click the explorer** name on the [View explorers](https://console.runzero.com/deploy/explorers) page to see the configuration options. You can update these by clicking the `Edit` button on the top of the page. 2. **Sites** - By default, explorers can be used across all sites. If you have multiple sites, you may want to tie an explorer to a specific site to avoid accidentally scanning the wrong site with an explorer. 3. **Concurrent tasks** - Explorers with Linux based operating systems (including macOS) can perform multiple tasks at once. - We recommend keeping this number of tasks between 1-4 for most scenarios. - If you are running a large scan like an RFC1918 scan, you will not want to run multiple tasks at the same time. 4. **Tags** - You can apply tags to an explorer that will be added to any asset discovered with that explorer. 5. **Passive traffic sampling** - You will also see the options to enable passive traffic sampling on this page. - Simply pick the interfaces you want to listen on, the site to associate the assets with, and the discovery scope to start the discovery. - Passive tasks will start in 5 minute increments and dynamically adjust based on the traffic volume the explorer is seeing. - You do not need to worry about resources with runZero passive traffic sampling since it limits usage to a single core. - This is possible since we only listen for a subset of the traffic that is useful for asset discovery, and any traffic that is not able to be processed is simply dropped. #### Explorer details page 1. System details - Every explorer reports basic info like Executable path, PID, and Memory usage. - This can be helpful as a first step to diagnose issues rather than SSH-ing into the host. 2. Tasks - You can also see every task the explorer has performed on this page. - `source:runzero` will show active scans - `source:sample` will show passive traffic sampling tasks 3. Diagnostics - Explorer diagnostics are also captured as needed. - You can trigger a new capture by clicking _Update diagnostics_. ### Credentials {#201credentials} The demo below shows you a walkthrough of the credentials section. The written form can be found below the demo. 1. The [Scanning with credentials](https://console.runzero.com/credentials) page is where you will manage all credentials for SNMP and integrations. 2. Clicking _Add credential_ will allow you to select the credential type, and you will be given a form depending on what is needed for that credential type. 3. Setting a credential as _Global_ will allow all users to use it in every Organization. 4. In most cases, you will limit a credential to a specific Organization. ### Tasks {#201tasks} There are four pages for managing tasks in runZero depending on what you are trying to do: 1. [Tasks](https://console.runzero.com/tasks/search/all) is a hub for tasks of all types. You can search all of your tasks here and configure all types of tasks including active, passive, and integration connections. - `source:runzero` shows active tasks. - `source:sample` shows passive tasks. - `not source:runzero not source:sample` shows integration connections. - `type:recur` shows all tasks scheduled to run on a cadence. - `status:error or status:stopped` shows all tasks that did not finish for some reason. 2. [Scan](https://console.runzero.com/data-sources/scan) provides a view of all active scans you have done thus far, and you can configure new active scans on this page. 3. [Monitor](https://console.runzero.com/data-sources/monitor) provides a view of all passive tasks that have happened so far, and you can configure new passive traffic sampling tasks or import PCAPs on this page. 4. [Integrate](https://console.runzero.com/data-sources/integrate) provides a list of supported integrations and allows you to configure them through that page. ### Configuring an active scan The demo below shows you a walkthrough of the active scan section. The written form can be found below the demo. 1. **Navigate to Tasks** and click _Scan > _ to configure an active scan. - A [Standard scan](https://console.runzero.com/scan/) provides the full suite of configuration options - A [Template scan](https://console.runzero.com/tasks/templatesNewScan) will use a pre-configured scan template which allows you to manage configurations across many tasks at once. You will be able to edit some parts of these on a per task basis like the discovery scope. - An [RFC1918 scan](https://console.runzero.com/scan/?ScanPreset=rfc1918) scans the entire RFC1918 space and allows minimal configuration like the packets per second and subnet sampling rate. - [More information on subnet sampling](https://help.runzero.com/docs/playbooks/achieving-rfc1918-coverage/#rfc1918-scanning-step2) is available. 2. **Configuration options** - In most cases, you will only need to update the configuration options on the Standard tab of your scan configuration. - Here are the commonly updated options: 1. **Site** - ideally all assets are under a single Primary site, but you may have reason to have multiple sites. 2. **Explorer or Hosted zone** - explorers are your locally deployed runZero explorers and Hosted zones are the runZero cloud hosted explorers. You can use the Hosted zones to scan public IP ranges and domains. Change explorer to None to select a Hosted zone. 3. **Scan rate** - packets per second for the explorer to max out at. This defaults to 1000 but can usually be increased in most networks. 4. **Discovery scope** - using `defaults` here will simply use the site’s subnets configured at the site level. You can also put IP ranges, domains, or dynamically populate the scope based on your inventory with the keywords like `public:all`. - More [information about discovery keywords](discovering-assets.md#discovery-keywords) is available. 5. **Schedule** - you can set scans to go hourly, daily, weekly, etc based on your needs. 6. **Scheduling grace period** - this tells the task how long to wait if the explorer is already in use. If you have multiple tasks running on the same explorer, it can be helpful to set this to 0 to avoid tasks failing due to explorer already being in use. - More information is available about [advanced scan configurations](discovering-assets.md#advanced-scan-options). #### Configuring passive traffic sampling The demo below shows you a walkthrough of passive traffic sampling section. The written form can be found below the demo. 1. **This was covered earlier** in the Section on managing explorers, so this is all duplicate information. 2. **Navigate the the explorer** you would like to configure passive traffic sampling on and follow these steps: - You will also see the options to enable passive traffic sampling on this page. - Pick the interfaces you want to listen on, the site to associate the assets with, and the discovery scope to start the discovery. - Passive tasks will start in 5 minute increments and dynamically adjust based on the traffic volume the explorer is seeing. - You do not need to worry about resources with runZero passive traffic sampling since it limits usage to a single core. - This is possible since we only listen for a subset of the traffic that is useful for asset discovery, and any traffic that is not able to be processed is simply dropped.
Note
If you do not have a TAP or SPAN configured, the passive traffic sampling will only see broadcast traffic which is only recommended for testing not production use cases.
#### Configuring an Integration connection The demo below shows you a walkthrough of the integrations section. The written form can be found below the demo. 1. Navigate to the [Integrate page](https://console.runzero.com/data-sources/integrate). 2. Identify the integration of interest and click _Configure_. 3. You can create a new credential by clicking that option in the form or select an existing credential you created on the Credential page. 4. All integrations will have these options - **Explorer** - all integrations can run from an explorer if needed for self-hosted services like Active Directory. With that being said, in most cases you can leave this as None to run directly from the Console. - **Site** - all integration assets will attempt to merge with assets in `all` sites in runZero, but you can set a backup site for unmerged assets if needed. Again, it’s highly recommended to use a single Primary site for this as well.
Note
If you self-host runZero, it is recommended to run integrations from explorers to avoid resource contention on the console while other tasks are processing.
5. Depending on the integration, you will have additional options which are all documented on the documentation page for that integration. 6. There is more [documentation about integrations](integrations-inbound.md) available. ## Automated asset tracking Once your asset discovery and integration tasks are all configured, you can start keeping tabs on changes in your inventory. You can do this in a few ways: 1. **Queries** are saved searches of your inventory can be used to keep track of how many assets or services of a specific type are in your inventory. 2. **Goals** are queries with targets related to count or percentage of assets and an optional time window. 3. **Alerts** allow you to trigger an activity like an email or webhook when there is a match in your inventory. 4. **Asset ownership** allows you to keep track of who owns what. This allows you to skip pivots during investigations when you need to take action on an asset. Each of these will be covered in detail below. ### Queries The demo below shows you a walkthrough of the queries section. The written form can be found below the demo. 1. You can see the out of the box queries by navigating to the [Queries](https://console.runzero.com/queries) tab in runZero. 2. You will notice a few key attributes: - **Name** - quick summary of what the search will show. - **Matches** - how many assets you have in your inventory currently that match the query. - **Severity** - level of impact if exposed. - **Risk** - level of impact combined with the likelihood of exposure. - **CVEs** - CVEs this search is related to. 3. You can search the Queries based on these attributes as well. Here are a couple common searches: - High or critical risk with matches in the inventory - [(risk:high or risk:critical) matches:>0](https://console.runzero.com/queries?search=%28risk%3Ahigh%20or%20risk%3Acritical%29%20matches%3A%3E0) - Queries with an associated CVE with matches in the inventory - [cve:"CVE%" matches:>0](https://console.runzero.com/queries?search=cve%3A%22CVE%25%22%20matches%3A%3E0) 4. You can view the details of any query by clicking the name. 5. The details will show a description, the search string, and allow you to test the query. 6. Vulnerability settings allow you to create your own vulnerability records from the runZero queries. When there is a match, it will show up on the asset as well as in the vulnerability inventory. 7. To create custom queries, you click _Create query_ on the main Queries tab. This will provide you the same options as the past query details page did for you to update. It is recommended to only match on live assets in most scenarios and to test the query prior to saving. ### Goals {#201goals} The demo below shows you a walkthrough of the goals section. The written form can be found below the demo. 1. Goals build upon queries by allowing you to set targets related to them. In addition to queries, you can set goals related to asset risk and ownership. 2. For example, you may want to set a goal related to the `SSH password authentication on internet-facing host` query meaning all of your internet facing SSH services require SSH keys. 3. You follow these steps to create a goal: - Click [New goal](https://console.runzero.com/goals/new) on the Goals tab. - Pick the type of System query, Custom query, Asset risk, or Asset ownership depending on your goal. - Set the Permissions to either Global to apply to all Organizations or toggle Global off to select specific Organizations. - After clicking _Next_, you have optional inputs including description, notes, target date, and the option to pin to the dashboard (recommended) for tracking. - Click _Next_ again to set your parameters for the goal. - If you are using a query, you will pick your query and set the target asset count or percentage. - If you are doing risk or ownership, you will simply set your target asset count or percentage. - Review and save your goal to start tracking it. - Once goals are configured, you can see the progress on your dashboard if you selected that option or the Goals tab. ### Alerts {#201alerts} The demo below shows you a walkthrough of the alerts section. The written form can be found below the demo. 1. You can see most of the events that can trigger alerts in runZero by reviewing the [events tab](https://console.runzero.com/alerts/events). 2. Creating an Alert requires three main steps: - Create a [template](https://console.runzero.com/alerts/templates) for the alert to use - this will be JSON or Email. - Create a [channel](https://console.runzero.com/alerts/channels) for the alert to go to - this will be an Email address or HTTPS webhook. - Create a [rule](https://console.runzero.com/alerts/rules) for the trigger conditions to watch. - For more detailed instructions, we recommend following this playbook on [creating alerts on asset and service changes](https://help.runzero.com/docs/playbooks/alerting-on-queries/). 3. If you do not need the alert to go to an external system, you can also just create a rule that triggers a local alert in runZero. You can see your local alerts on the [alerts tab](https://console.runzero.com/alerts). 4. In addition to monitoring your inventory, rules can be used to automatically update your assets based on what you know about your environment. 5. For example, you can set Asset Ownership on a set of assets like this: - Click [Create rule](https://console.runzero.com/alerts/rule/create/) - Select `asset-query-results` and click [Configure rule](https://console.runzero.com/alerts/rule/create/asset-query-results) - Optionally set the Organization, site, explorer, or task type if you do not want it triggered on all events - Enter your query to identify the assets you want to update - Set number of matches to is greater than 0 - Change the action to Modify asset - Set the Ownership values of interest 6. Here is a full list of asset values that can be updated in rules: - OS vendor - OS product - OS version - Hardware vendor - Hardware product - Hardware version - Asset type - Asset criticality - Asset tags - All Ownership types ### Asset ownership The demo below shows you a walkthrough of the asset ownership section. The written form can be found below the demo. 1. Asset ownership in runZero allows you to easily track who owns what in your environment. 2. Asset ownership can be populated on an asset in three ways: - Automatically through integrations - Automatically through rules (see last section on alerts for an example) - Manually through the Inventory or Asset detail pages 3. Superusers can set ownership types in the [Ownership tab](https://console.runzero.com/ownership-types). - Assets can have up to 10 ownership types to allow for flexibility based on your environment. - The Asset owner is the default owner that will be populated by integrations. - You can add more types by clicking the _Add ownership type_ button - You will create a name, optional reference, and set visibility to users as hidden or visible. - Reference options: 1. **None** - the ownership value can be anything. 2. **Directory user or group** - it will provide a dropdown list while updating the ownership to use Active Directory data only. 3. **runZero user or group** - it will provide a dropdown list while updating the ownership to use runZero users or groups only. 4. Once types are configured, all users will be able to set the ownership types on the assets based on the configuration set. 5. You can search assets based on ownership in a few ways: - Asset has an owner - [has_owner:t](https://console.runzero.com/inventory?search=has_owner%3At) - Owner is named Tyler - [owner:tyler](https://console.runzero.com/inventory?search=owner%3Atyler) - Owner count is greater than or equal to 2 - [owner_count:>2](https://console.runzero.com/inventory?search=owner_count%3A%3E2) - Owner type IT is known - [owner:it](https://console.runzero.com/inventory?search=ownership_type%3Ait) ## Using the API The runZero API allows you to export your inventory data, extend functionality, and automate processes. ### Authentication options The demo below shows you a walkthrough of the authentication options section. The written form can be found below the demo. Depending on the use case, you can authenticate to the runZero API in a few different ways: 1. Account level access - [API clients](https://console.runzero.com/account/api/clients) allow for Client ID and Secret authentication. API clients have full read/write access to the entire account, and can perform any action via the API. - [Account API keys](https://console.runzero.com/account) allow for HTTP Basic authentication. Account API keys have full read/write access to the entire account, and can perform any action via the API. 2. Organization level access - **Creating organization level tokens** - in order to create Organizational level access tokens, navigate to [Organizations](https://console.runzero.com/organizations), click the organization of interest, and click _Edit organization_. - **Organization API tokens** allow full read/write access to the Organization. This token can perform any action via the API on this specific Organization. - **Export tokens** are read only tokens that can be used to export the inventory data from runZero. This is the most commonly used token since exporting the data is the most common use case. - **Download tokens** allows for automated explorer deployments. The only access it has is the ability to download the explorer binary for installation on a host. ### Common Use Cases Here are a few common use cases for the API. #### Exporting inventory 1. Use case - It is common for customers to want their inventory data populated elsewhere like a SIEM or CMDB for other teams to consume downstream. - While runZero has native integrations for tools like Splunk and ServiceNow, there are plenty of other tools customers have integrated with.
Note
All exports are done at the Organizational level, so if you have multiple Organizations, you may need to do multiple exports.
2. API endpoints - [Asset inventory, JSON format](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Export/exportAssetsJSON) - other format options include JSONL, CSV, and XML. - [Service inventory, JSON format](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Export/exportServicesJSON) - other format options include JSONL and CSV. - [Vulnerability inventory, JSON format](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Export/exportVulnerabilitiesJSON) - other format options include JSONL and CSV. - Additional inventory export options include Wireless, Software, Users, and Groups. 3. Sample scripts - [Basic export with a few different searches](https://github.com/tdiderich/runZero-scripts/tree/main/export) - [Export and transform to CSV](https://github.com/tdiderich/runZero-scripts/tree/main/export-to-csv-specific-fields) - [Export and stream to PowerBI](https://github.com/tdiderich/runZero-scripts/tree/main/export-power-bi) #### Scan task scheduling 1. Use case - If you have your SOAR hooked up to runZero, you may want to search the inventory for specific IP addresses, hostnames, etc. - But, what happens if there is no result? You may want to trigger a scan. 2. API endpoints - To run the search, you would simply use the export endpoints above. - To run the scan, you use the [scan endpoint](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Organization/createScan). 3. Sample script - [Search results or scan](https://github.com/tdiderich/runZero-scripts/tree/main/search-results-or-scan) #### Custom integrations {#201customintegrations} 1. Use case - Many customers have inventory data in tools not currently supported by runZero’s native integrations. - Luckily, runZero supports Custom Integrations as well. - So, you can connect to your other sources, transform the data to the runZero data model, and upload that to merge with your runZero inventory. 2. API endpoints - [View custom integrations](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Account/getAccountCustomIntegrations) - [Create new custom integration](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Account/createAccountCustomIntegration) - [Upload custom integration data and create task to process](https://app.swaggerhub.com/apis/runZero/runZero/3.10.11#/Organization/importCustomIntegrationAssets) 3. Sample scripts - [Tanium](https://github.com/tdiderich/runZero-scripts/tree/main/sdk-sample-scripts/tanium) - [Cylance](https://github.com/tdiderich/runZero-scripts/tree/main/sdk-sample-scripts/cylance) - [JAMF](https://github.com/tdiderich/runZero-scripts/tree/main/sdk-sample-scripts/jamf%5C) --- docs/organizations.md --- title: "Organizations" --- An organization represents a distinct entity; this can be your business, a specific ((department)) within your business, or one of your customers. All actions, tasks, Explorers, scans, and other objects managed by runZero are tied to specific organizations and isolated from each other. Your active organization can be switched by using the dropdown selector at the top right of the runZero Console. If your default role is Viewer or higher, you can select **All Organizations** from the dropdown to view the data for all of your organizations in the Dashboard and Inventory. The Queries page also supports the All Organizations view. Pages that are not compatible with the All Organizations view will be hidden until a single organization is selected. runZero Community Edition is limited to a single organization. ## Use cases for organizations It is common to segment your assets to multiple organizations based on a few common requirements: - **RBAC**: Users will only be able to see the assets in the organizations or the children of organizations they're added to. - **Environments**: It is possible you do not want your development, production, or other assets in one pool and would prefer them to be segmented. - **Customers**: Service providers generally have one organization per customer. ## Creating organizations Organizations can be created, modified, and deactivated by going to the organizations section within the console. Click the Organizations link under Global Settings. ## Organization configurations - **Name**: Name of the organization. - **Parent organization**: Allows for sub-organizations, limited to three levels of nesting. Permissions will be inherited based on most privilege. - **Description**: description of the organization. - **Stale asset expiration**: Sets the number of days before stale assets are removed from the inventory. This applies to online and offline assets not seen within the configured number of days. - **Offline asset expiration**: Sets the number of days before offline assets are removed from the inventory. This applies to offline assets not seen within the configured number of days. - **Stale integration attributes expiration**: Sets the number of days before stale integration attributes are removed from the inventory. Optionally keep the latest set of integration attributes per source, even if it is older than the threshold. - **Stale vulnerability expiration**: Sets the number of days before stale vulnerabilities are removed from the inventory. - **Scan data expiration**: Sets the number of days before completed scans are removed from the platform. This applies to the scan task metadata as well as the raw data files and change reports. ## Projects A ((project)) is a special type of organization designed for temporary use. They behave like organizations, and can have sites defined within them. The important difference is that projects cannot be parents of organizations or other projects, automatically become read only after 30 days, and are automatically deleted after 90 days. While organizations allow you to customize expiration times, the expiration times for projects are fixed. Your runZero license includes the addition of up to five times as many project assets as the total number of licensed live assets. For example, if your license includes 1,000 live assets, you can have up to 5,000 project assets total. The total number of assets in organizations and projects can be seen on your [license information](https://console.runzero.com/license) page in the runZero console. If you decide that you want to keep a project indefinitely, it can be converted into an organization. Note that organizations support custom [data retention](data-retention.md) settings that you can edit to your requirements. ## Organization and project details Click on the name of an organization or project to get to the details page. This page includes basic details about the organization or project, as well as its place in the organization hierarchy. --- docs/sites.md --- title: "Sites" --- By default, your account includes a single organization, which itself contains a single site, named Primary. If the only site in an organization is deleted, a replacement will be created automatically. Similarly, if the last organization is removed, a replacement will be created. You can rename organizations and sites at any time. Every organization has at least one site, but may have multiple sites. A site represents a distinct network segment, usually defined by addressing or accessibility. Sites in runZero do not necessarily correspond to physical sites or locations. Instead, they are used to represent distinct networks that may have overlapping address space. This allows for multiple sites to use the same ((RFC1918)) space, something common in retail, while still being possible to differentiate their assets within the inventory. Because sites represent separate networks, if you set up two sites and scan the same devices from both, you will end up with two copies of the resulting assets, one set for each site's network. All analysis actions within runZero occur at the site level. For example, reports such as the switch topology report analyze a single site's devices, so you will likely want to avoid splitting routers and non-router assets into separate sites unless they are truly on separate disconnected networks. ## Use cases for sites For ((flat networks)), where every IP address can reach any other address on the network, a single site is usually enough, and avoids the possibility of accidentally creating ((duplicate assets)) by scanning the same devices from multiple sites. Sites are recommended for complicated, sprawling, and highly-segmented environments. Two circumstances that could lead to multiple sites: - **Overlapping IP space**: sites will allow you to differentiate identical IPs that are actually different machines if you have overlapping IP space. - **Highly complex network**: sites would not be required in this case, but they can be used as an organizational tool. ## Creating sites The ability to create sites must be enabled on your account before you can add new sites. If you do not see a **New Site** button, please reach out to [support@runzero.com](mailto:support@runzero.com) to have this feature enabled on your account. To create a new site, click the **New Site** button on the top of the [sites](https://console.runzero.com/sites) page. ## Site configurations - **Name**: The name of your site. - **Description**: The description can help identify the purpose of the site. - **Default scan scope**: The default scan scope will be pre-populated when creating scans for this site. - **Default scan exclusions**: The default scan exclusions will be pre-populated when creating scans for this site. - **Registered subnets**: Registered subnets can be used to automatically tag assets, services, screenshots, and software that fall within each subnet. ## Subnet tagging Tagging based on subnet works a little differently to directly tagging assets or tagging them via a task. If a subnet is defined to have a specific tag, then only assets in that subnet will be given that tag. The tag will be removed from any assets not in the subnet, even if set by a task or set manually. ## Importing subnets Site subnets can be created or updated based on a CSV file import as part of the site configuration. Here is a sample CSV for import: ```csv cidr,tags,description 192.168.0.0/16,purpose=endpoints,"Headquarters endpoint subnet ""quoted text""" 10.0.0.0/24,purpose=wifi,"Headquarters wireless subnet, with comma" 2001:db8::/32,"foo=bar,foobar",ipv6 subnet 1.2.3.4/16,, ``` ## Importing and exporting sites Site configurations can be created or updated based on a CSV file import. [Import your CSV](https://console.runzero.com/sites/import) from the sites page. The CSV format should include the following: ```csv name,description,scope,exclusion,subnet_ranges,subnet_tags,subnet_descriptions ``` Your site configurations can also be exported as a CSV from the sites page. ## Sites and Explorers Sites can be tied to specific Explorers, which can help limit traffic between low-bandwidth segments. The site configuration allows a default scan scope to be defined, along with an optional list of excluded scan scopes. These fields can be used to set the scan scope for scans of the site. If you would like to tie an Explorer to a site, navigate to the [Explorers](https://console.runzero.com/deploy/explorers) page, click the Explorer you would like to tie to the site, and then click configure. After that, you will see a dropdown with your site options. --- docs/self-hosting.md --- title: "Self-hosting runZero" date: 2021-06-15 --- ## Background The ((self-hosted)) version of runZero allows you to run the entire platform ((on-premises)) or within your own cloud environment. This platform is functionally identical to the hosted service, provides a fully-offline mode, and does not send any inventory data back to runZero. While self-hosting is less common, here are a few reasons your company might choose to: - ISO compliance requirement - Other compliance requirement - Prefer data on-premise Self-hosting must be explicitly enabled for your account. Self-hosting is available if you have a runZero Platform license, or if you are running an initial trial for a platform license. Please contact your runZero sales representative for further information. Self-hosting is not available for the free Community Edition of runZero. ## Requirements {#self-hosting-requirements} Before you get started, make sure your system meets the following requirements. ### Hardware requirements **Recommended production** system requirements: - 12 CPU Cores at 2 GHz or faster - 1TB of local disk storage - 128 GB of RAM **Minimum production** system requirements: - 4 CPU Cores at 2 GHz or faster - 100 GB of local disk storage - 32 GB of RAM (more for large sites) **Minimum testing** system requirements: - 2 CPU Cores at 2 GHz or faster - 20 GB of local disk storage - 16 GB of RAM (more for large sites) ### Sample customer deployments **Up to 1M assets**: - Two virtual machines (one for console and one for database) - 32 CPU Cores at 2 GHz or faster - 1TB of local disk storage - 128 GB of RAM **Up to 500K assets**: - 32 CPU Cores at 2 GHz or faster - 1TB of local disk storage - 128 GB of RAM **Up to 50K assets**: - 16 CPU Cores at 2 GHz or faster - 1TB of local disk storage - 64 GB of RAM ### Software requirements - PostgreSQL 13 or newer (16+ preferred, our installer can install this for you) ### Supported operating systems - Ubuntu 18.04 and newer running on x86_64 - Red Hat Enterprise Linux 7.x and newer running on x86_64 - CentOS Linux 7.x and newer running on x86_64 - Oracle Linux 7.x and newer running on x86_64 - 8.x must be 8.4+ with UEK 5.4+ or kernel 4.18+ - 7.x must be 7.9+ with UEK 5.4+ or kernel 3.10+ - Debian Linux 9.x and newer running on x86_64 Windows Subsystem for Linux is not supported. The runZero console can be installed in a minimal install of Ubuntu or any RHEL derivative; you do not need to install a GUI. The default disk partitioning scheme will work, but you may want to consider using LVM if you plan to resize the disk later. #### Note about Debian By default, Debian Linux uses the `su` command instead of `sudo`. It also requires that you use the command `su -` to become root, not just `su`, in order to update the `PATH` to include system administration commands such as `useradd`. If you receive an error during installation saying `executable file not found in $PATH`, this is the most likely reason. ### Connectivity The self-hosted runZero platform requires connectivity to the runZero SaaS backend over TCP port 443 (TLS) to obtain online updates. The specific IP addresses and hostnames depend on your deployment model and region and can be found below. #### United States {#selfhosting-us} The console hostname is `console.runzero.com`. IPv4 * 13.248.161.247 * 76.223.34.198 IPv6 * 2600:9000:a415:cd87:fbe5:476a:3533:69f2 * 2600:9000:a716:ee91:85f9:3c9:48c9:59b9 #### Germany {#selfhosting-de} The console hostname is `console-eu.runzero.com`. IPv4 * 15.197.131.232 * 3.33.248.90 IPv6 * 2600:9000:a603:e925:542d:6d40:6897:bc3a * 2600:9000:a70e:635f:71bd:bb0a:8e43:9466 The self-hosted runZero platform will also require connectivity to the following sites over TCP port 443 during installation and for subsequent software updates. * apt.postgresql.org ### Platform Address & TLS Configuration The system running the runZero platform should have a static IP address. The Explorers need to be able to validate their HTTPS connection to the platform via a TLS certificate. By default, the runZero platform installer will set up a self-signed certificate for the console's IP address, and downloaded Explorers will be preconfigured with the appropriate URL and certificate so they can make a verified connection.
Note
Some components of the application still reference the name "Rumble" for backwards compatibility. The documentation will be updated as these are changed.
If instead you plan to use a real certificate from an internal or public CA for your runZero console deployment, you will want to assign the console server a DNS name, and edit `RUNZERO_CONSOLE` in the configuration to contain the fully qualified domain name. The `TLS_CERT` and `TLS_KEY` should be set to point at the appropriate certificate and private key files. The console should then be restarted via `runzeroctl restart`. Newly downloaded Explorers will then be preconfigured with the right URL and certificate. Because Explorers are preconfigured with the console address during download, if the IP address and/or DNS name are changed at a later date, the Explorers may need to be redeployed to receive the updated address. If the platform is being deployed behind a reverse proxy, the reverse proxy may need additional configuration to pass the `Origin` header through to the runZero Console. This header is required for CSRF protection, and some functionality (such as the data tables throughout the product) will not work if the header isn't passed through, or is incorrect. ## Offline mode The self-hosted version of runZero has the ability to run in [offline mode](docs/self-hosting-offline.md). In this mode, the runZero update service is not used and [offline updates](docs/self-hosting-offline.md#offline-update) must be applied manually. Enable this mode if you're in an isolated network or you don't want your self-hosted runZero console to make any connections to the internet. In addition to disabling online updates, offline mode also disables certain DNS probes that could reflect responses to the internet during a scan. ## Installation steps **For offline installs please see** [offline installation](docs/self-hosting-offline.md#offline-install). **For installs that use your own database credentials see** [Installation with your own PostgreSQL database](#manual-database-install). Here's what the installation process will do: - Set up PostgreSQL and create a dedicated user with a strong password. - Generate TLS certificates for your IP address located in `/etc/runzero/certs`. - Generate a configuration file at `/etc/runzero/config` and set some defaults. - Create a `systemD` or RC service for the runZero platform. ### Step 0: Ensure a clean starting environment If you've previously ran the installer and encountered an issue related to disk space, memory, or repository verification, you may need to clean up some temporary files before retrying the install: Remove any temporary files left from the previous install: ```shell # rm -rf /tmp/update-tmp* /tmp/runzero-updates* ``` On RHEL and CentOS systems, clear any leftover PostgreSQL remnants: ```shell # dnf remove postgresql # rm -rf /var/lib/pgsql/ ``` Use the installer binary to purge any leftovers: ```shell # ./runzero-install.bin uninstall --purge ``` ### Step 1: Download and run the installer - Go to [https://console.runzero.com/deploy/download/platform](https://console.runzero.com/deploy/download/platform). - Copy the command directly from the download page and run it in your terminal. This will download the installer and mark it as executable. The download path for the installer is uniquely keyed. - Run the installer. - By default, the console will be installed to `/opt/runzero`. If you need to change this, you can use the `--install-directory` option. ### Step 2: Ensure sufficient disk space By default, the runZero console will store data in the `storage` directory underneath the install directory. By default, that will be `/opt/runzero/storage`. The `storage` directory must have enough space to store all unexpired scan data and asset data. If necessary you can override its location by setting the `RUNZERO_STORAGE_PATH` variable in the runZero configuration file `/etc/runzero/config`. You will also want to ensure that the temporary directory has plenty of space for temporary files such as software and content updates. If the `TMPDIR` environment variable is set, that directory will be used; otherwise the default is `/tmp`. ### Step 3: Initialize the admin user After you've installed the runZero platform, you will have access to the runZero CLI `runzeroctl`. To initialize an admin user, run: ``` runzeroctl initial [email address] ``` ### Step 4: Sign in to your self-hosted console If everything is set up correctly, you can sign in to your console at `https://YourInternalIPAddress`. Note that you may need to enable HTTPS to pass through the Linux system firewall. Example commands: **Ubuntu Linux:** `sudo ufw allow https/tcp` **RHEL/CentOS/Oracle:** `sudo firewall-cmd --add-service=https` To make a `firewall-cmd` change permanent across reboots, run the command a second time with the `--permanent` flag added. ## Installation with your own PostgreSQL database {#manual-database-install} runZero defaults to installing and configuring a PostgreSQL user and database for you. If you would like to provide your own details this option will allow you to override that behavior. ### Requirements - PostgreSQL 13 or newer (16+ preferred) - [Password authentication](https://www.postgresql.org/docs/current/auth-password.html) must be enabled. - Two extensions are required: [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) and [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html). These may be supplied as part of a `contrib` package rather than as part of the main PostgreSQL server install, depending on where you obtain your PostgreSQL packages. **PostgreSQL example to enable extensions and add a database/user** ```sql CREATE DATABASE runzero TEMPLATE='template0' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8'; CREATE USER runzero WITH PASSWORD 'YOURPASSWORD'; GRANT ALL PRIVILEGES ON DATABASE runzero TO runzero; \connect runzero; CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; ``` **Steps to install the self-hosted runZero platform with your own database credentials** 1. Run this install command as root: ```bash ./runzero-platform-[VERSION]-linux-amd64.bin install --manual-database ``` 2. Edit your runZero configuration and add your database details in `/etc/runzero/config`. The line you need to edit is: ```bash DATABASE_URL=postgres://runzero:{DB_PASSWORD}@127.0.0.1:5432/runzero?sslmode=disable ``` Change this to match your credentials. You need to set the user, password, host, port, and database name. Here is the format: ```bash DATABASE_URL=postgres://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?{DB_OPTIONS} ``` 4. Verify the self-hosted runZero platform can connect to your database with this command. `sudo runzeroctl database verify` 5. Once your database is configured and verified you can restart the self-hosted runZero platform service `sudo systemctl restart runzero-console` ## runZero updates **For offline updates please see** [CLI update with offline mode](docs/self-hosting-offline.md#offline-update). The self-hosted runZero platform must be updated prior to first use. The `runzeroctl` command can be used to download the update and then restart the service after the update is complete. You can update the platform and scanners at the same time or separately with the [CLI update management commands](#cli-update-management). ## Managing users You can manage users inside your self-hosted runZero platform console at `https://YourInternalIPAddress/team` or via the [runZero CLI](#cli-user-management) Some things you can manage: - Adding, deleting, and listing users - Resetting passwords - Changing default roles - Viewing details - Changing organization roles ## CLI service management ### Start the runZero service Starts the runZero platform service. ```bash runzeroctl start ``` ### Stop the runZero service Stops the runZero platform service. ```bash runzeroctl stop ``` ### Restart the runZero service Restarts the runZero platform service. ```bash runzeroctl restart ``` ### Install the runZero platform Install the runZero platform service and all required dependencies such as PostgreSQL. Creates a systemd service, generates cron jobs, and generates a configuration file in `/etc/runzero/config`. ```bash runzeroctl install ``` ### Uninstall the runZero platform Stop and remove the runZero platform service from systemd and removes the generated cron jobs. This does not remove your PostgreSQL database, and it retains your data. ```bash runzeroctl uninstall ``` ### Purge the runZero platform Stop and remove the runZero platform service from systemd and removes the generated cron jobs. This will delete your runZero database and remove all the runZero directories `/etc/runzero` and `/opt/runzero`. ```bash runzeroctl purge ``` You can uninstall and purge everything except the database and your PostgreSQL settings with this flag: ```bash runzeroctl uninstall --purge --ignore-database ``` ### Run the runZero platform manually Starts the runZero platform manually. Logs will be written to standard output. ```bash runzeroctl server ``` ### Verify your database is reachable Attempts to connect to your database using your self-hosted runZero platform configuration. It will either succeed or display an error. ```bash runzeroctl database verify ``` ## CLI update management ### Update the runZero platform and scanners Updates the runZero platform service and runZero scanners. You can use the optional parameter `force` to force the update even if the current installation is the latest version. ```bash runzeroctl update [--force] ``` ### Update the runZero platform Updates just the runZero platform service. You can use the optional parameter `force` to force the update even if the current install is the latest version. ```bash runzeroctl update-platform [--force] ``` ### Update the runZero scanners Updates just the runZero scanners. You can use the optional parameter `force` to force the update even if the current installation is the latest version. ```bash runzeroctl update-scanner [--force] ``` ## CLI user management ### Create the initial administrator account Creates the initial admin user for a new installation. You must provide an email address. ```bash runzeroctl initial ``` ### List user accounts Lists all the users along with their email address, full name, and current roles. ```bash runzeroctl user list ``` ### Add a user account Creates a new user account under the initial administrator user. You must provide an email address. ```bash runzeroctl user add ``` ### Delete a user account Deletes a user account. You must provide an email address. This cannot be undone. ```bash runzeroctl user delete ``` ### Get user details Gets the details for a user account. You must provide an email address. Provides information such as full name, date created, last sign in IP, last sign in time, last activity, default organization role, and their current roles. You must provide an email address. ```bash runzeroctl user details ``` ### Set a user role Sets a user's role to the role provided. Email and role must be provided. The organization is optional. If the organization isn't provided this sets their default role. ```bash runzeroctl user set-role [organization name or organization ID]: ``` ### Reset a user password and MFA This will generate and apply a new password for the specified user. The password will be printed to the terminal. You must provide an email address. This reset process also clears any associated MFA tokens. ```bash runzeroctl user reset ``` ## CLI organization management ### List all organizations Lists all the organizations by their name and ID. ```bash runzeroctl organization list ``` ## Advanced configuration The file at /etc/runzero/config can be modified to support a wide variety of configurations. After making changes, apply them by running `runzeroctl restart`. ### Email server runZero uses an SMTP server for user account invitations and notifications. The default configuration assumes that a SMTP server is available on localhost that does not require authentication: ```bash SMTP_SERVER=127.0.0.1:25 SMTP_AUTH_METHOD=none ``` runZero will automatically use STARTTLS with plaintext SMTP servers and validate the certificate. In internal environments where the SMTP server is not using a valid TLS certificate, verification can be disabled by setting: ```bash SMTP_TLS_NOVERIFY=true ``` Transport-layer TLS (instead of STARTTLS) can be configured with: ```bash SMTP_TLS=true ``` If authentication is required, the following three settings should be configured: ```bash SMTP_AUTH_METHOD=plain SMTP_AUTH_USER=YourUsername SMTP_AUTH_PASS=YourPassword ``` *Note: at this time the only supported authentication methods are "login" and "plain".* Emails are sent from `noreply@rumble.run` by default, but this can be changed by setting the `FROM_EMAIL` option: ```bash FROM_EMAIL=runzero@yourcompany.int ``` ### Hostname and port The RUNZERO_CONSOLE variable is used for creating inbound links, configuring deployed Explorers, and generating the default self-signed TLS certificate. This setting is how both users and deployed Explorers connect to the platform. ``` RUNZERO_CONSOLE=https://{IP ADDRESS OR HOSTNAME}:443 ``` Changing this setting may require regeneration of the TLS certificate and redeployment of Explorers. ``` runzeroctl generate-certificate ``` runZero can be configured to run on a different port with the CONSOLE_PORT setting. This port defines where the console listens, but users and Explorers still connect to the RUNZERO_CONSOLE value. In most cases this should match the port specified by the RUNZERO_CONSOLE. ``` CONSOLE_PORT=443 ``` ### TLS configuration {#tls-config-selhosted} runZero will generate a self-signed TLS certificate and serve all web requests using HTTP over TLS. The standard configuration uses a self-signed certificate stored in the filesystem: ``` TLS=true TLS_CERT=/etc/runzero/certs/cert.pem TLS_KEY=/etc/runzero/certs/key.pem ``` The certificate and key file are PEM encoded and can be replaced with any valid certificate. Please ensure that any new certificate lists the value of RUNZERO_CONSOLE in the list of Subject Alternative Names. Note that the key file must be unencrypted (not password protected). If you have a passphrase set, you can remove it using OpenSSL. For example: ``` # RSA key openssl rsa -in key.pem -out newkey.pem # DSA key openssl dsa -in key.pem -out newkey.pem ``` If a TLS-terminating reverse proxy is used (AWS ELB, nginx, etc), TLS can be disabled at the application level: ``` TLS=false ``` Please note that while the web interface can be accessed over plain HTTP in this scenario, Explorers will refuse to connect to a plain HTTP port, and features like WebAuthn MFA will not work unless the site is accessed through TLS. Specific TLS versions and ciphers can be configured. TLS versions are chosen by minimum and maximum: ``` TLS_VERSION_MIN=1.2 TLS_VERSION_MAX=1.3 ``` TLS ciphers may be chosen by profile name: * **default**: A set of strong ciphers, great for most configurations * **nist80052**: A set of strong ciphers, approved in [NIST 800-52r2](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-52r2.pdf). * **nist80052-aes256**: A set of strong ciphers, approved in [NIST 800-52r2](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-52r2.pdf), restricted to AES-256 variants Please note that TLS 1.3 ciphers work differently and if a specific set of ciphers is required, both TLS_VERSION_MIN and TLS_VERSION_MAX should be set to `1.2`. For example, to restrict runzero to **only** NIST 800-52r2 approved ciphers using AES-256, the following configuration should be used: ``` TLS_VERSION_MIN=1.2 TLS_VERSION_MAX=1.2 TLS_CIPHERS=nist80052-aes256 ``` TLS ciphers may also be chosen using comma-separated list of [cipher constants](https://golang.org/src/crypto/tls/cipher_suites.go). ### Database configuration runZero uses a PostgreSQL database for all platform data, except for raw scan files, change reports, and images processed from scans. By default, runZero will configure a local PostgreSQL server on the same system, with a random password, and without TLS encryption: ``` DATABASE_URL=postgres://runzero:{DB_PASSWORD}@127.0.0.1:5432/runzero?sslmode=disable ``` If separate database is preferred, any PostgreSQL server running 12.x or newer should work. TLS (sslmode=require) should be enabled when a non-local database server is configured. The default database pool (connection count) can be modified for high throughput environments: ``` DATABASE_POOL_COUNT=50 ``` ### Proxy configuration runZero makes outbound connections to receive platform updates (in online mode), to connect to third-party APIs, and to delivery webhooks for notifications. If a proxy server is required, it can be configured with this setting: ``` HTTPS_PROXY=host:port ``` A separate proxy may be configured for AWS connections. This takes precedence over `HTTPS_PROXY`: ``` HTTPS_PROXY_AWS=host-for-aws-services:port ``` In addition to standard HTTP proxies, a SOCKS proxy may be configured by specifying a URL like: ``` HTTPS_PROXY=socks5://socks.example.com:1080 ``` ### Storage configuration runZero uses local file storage to store raw scan data, change reports, and images retrieved from assets. This storage directory must be owned by the `rumble` user and be mounted below the /opt/runzero path. ``` RUNZERO_STORAGE_MODE=local RUNZERO_STORAGE_PATH=/opt/runzero/storage ``` Files within the storage directory are split up into two groups, assets and scans. The names of these can be changed by setting: ``` ASSET_BUCKET=assets SCAN_BUCKET=scans ``` To use AWS S3 for file storage instead, the following configuration can be set: ``` RUNZERO_STORAGE_MODE=s3 ASSET_BUCKET=company-runzero-assets SCAN_BUCKET=company-runzero-scans ``` If a non-AWS backend is used that is compatible with the S3 API, use the same AWS and bucket variables above but override `AWS_REGION` and set the `AWS_ENDPOINT_URL_S3` or `RUNZERO_STORAGE_ENDPOINT` parameter to the endpoint as appropriate. Reach out to runZero support if you run into any issues with the endpoint configuration. If the S3 buckets are in a different region than the environment, set the `RUNZERO_STORAGE_REGION` to the correct region for the buckets. If S3 is used, AWS must also be [configured](#aws-configuration), with at least the `AWS_REGION` variable set, even if a non-AWS backend is enabled. ### Secret configuration runZero uses three randomly generated secret tokens to secure the platform. These keys are hexadecimal strings generated by 16 bytes of random. Compatible values can be generated by OpenSSL: ``` $ openssl rand -hex 16 ``` The authentication key used for local storage HMAC operations. This key can be rotated as long as the service is restarted afterwards: ``` RUNZERO_STORAGE_KEY_SECRET={SECRET_32_HEX} ``` The session secret key is used to sign and validate browser session cookies. This key can be rotated, but doing so will invalidate all existing web sign-ins: ``` SESSION_SECRET={SECRET_32_HEX} ``` The DB key is used for encryption of sensitive fields (user password hashes). This key cannot be rotated, as password authentication will no longer work. If this key is changed, users must reset their password from the command-line or web interface using email before they can sign back in: ``` DB_KEY={SECRET_32_HEX} ``` ### AWS configuration The AWS region is required: ``` AWS_REGION=us-east-1 ``` The Access Key ID and Secret must be valid and correlated to a user with read-write access to the S3 buckets and read-only access to Secrets Manager. ``` AWS_ACCESS_KEY_ID=AKIA.... AWS_SECRET_ACCESS_KEY=SECRET.... ``` AWS Secrets Manager can be used to retrieve almost any configuration setting at startup. The Secrets Manager entries should match the key names of the configuration file. The secret name can be defined with: ``` AWS_SECRETS_MANAGER_KEY=rumble/production ``` In addition the variables above, most [AWS CLI environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) are also available for specific tuning. The location of the Explorer and scanner binaries can be changed with these settings. Note that these should still live under /opt/runzero or the service will not be able to load them: ``` RUNZERO_RELEASE_DIR=/opt/runzero/agent/ RUNZERO_SCANNER_RELEASE_DIR=/opt/runzero/scanner/ ``` ### Content security policy In the case of a non-standard S3 configuration (or S3-like deployment, such as minio), the Content Security Policy headers need to be configured to allow external image loads. The CSP_IMAGES setting can be used to specify one or more (comma-delimited) external image sources: ``` CSP_IMAGES=https://*.custom-storage-backend.lan ``` In additional to CSP_IMAGES, the following additional CSP settings are available: ``` CSP_SCRIPTS=https://*.myscripts.lan CSP_FONTS=https://*.myfonts.lan CSP_STYLES=https://*.mystyles.lan ``` ### Logging The self-hosted runZero console sends its ((logging)) output to standard output. On Linux this is picked up by Linux systemd, and stored in the ((journal)) where it can be queried with the `journalctl` tool. For example, to view the most recent hour of logs, with most recent messages first, you can run the following command: ``` journalctl --unit=runzero-console --since=-1hour --reverse ``` The ((journalctl)) output can be piped to a text file to send to runZero support. The systemd logging subsystem can be configured to send log messages to a local ((syslog)) daemon as well as the journal. Once logs are in syslog, they can be forwarded across the network to ((remote logging)) servers using the standard syslog protocol. Some Linux distributions, such as RHEL, are set up to forward logs from systemd to syslog by default. Other distributions, such as Ubuntu and Debian, don't include a syslog daemon in their default minimal server installs. To configure systemd to send logs to syslog, you can use the [ForwardToSyslog option](https://www.freedesktop.org/software/systemd/man/journald.conf.html#ForwardToSyslog=) in `/etc/systemd.conf`. Alternatively, some syslog daemons have an option to read the systemd journal; for example, rsyslog has [imjournal](https://rsyslog.readthedocs.io/en/latest/configuration/modules/imjournal.html). runZero's logs are output in [((CEE))-enhanced](https://cee.mitre.org/language/0.6/CEE_Transport-Syslog_Mapping.html) JSON format. This is compatible with rsyslog and [syslog-ng](https://www.syslog-ng.com/community/b/blog/posts/parsing-sudo-json-logs-building-a-syslog-ng-configuration), DataDog, and other common logging tools. For rsyslog, the [mmjsonparse](https://rsyslog.readthedocs.io/en/latest/configuration/modules/mmjsonparse.html) module can be used to filter the logs based on individual JSON fields, and [forward them to ((ElasticSearch))](https://www.rsyslog.com/json-elasticsearch/) or other JSON databases. The environment variable `LOG_MAX_LENGTH` can be set in runZero's config file to apply a limit to the length of each log line, in bytes of UTF-8 text. A value of 0 means no limit, other values below 480 are treated as 480. runZero will attempt to preserve the most valuable logging fields when truncating log output, and ensure that the result is still valid JSON. Note that the length limit is applied before any additional information systemd or syslog adds to the start of the line. The environment variable `LOG_FORMAT` can be set to `text` to disable the CEE and JSON format, and log in plain text. For example: ``` LOG_FORMAT=text LOG_MAX_LENGTH=512 ``` ### HTTP timeouts The self-hosted runZero Console allows you to change the built-in web server's HTTP timeouts. These can be changed through three configuration variables. You are able to set the HTTP idle, read, and write timeout. The default settings are below and don't usually need to be changed. ``` HTTP_IDLE_TIMEOUT_MINUTES=3 HTTP_READ_TIMEOUT_MINUTES=60 HTTP_WRITE_TIMEOUT_MINUTES=720 ``` ### Concurrent processing The runZero Console can process more than one completed task at a time if the `RUNZERO_CRUNCHER_INSTANCES` option is set to a value greater than 1. Tasks are only processed concurrently when they exist within different organizations, or the tasks are within the same organization, but different sites, and the task itself does not require cross-site asset merging. Most third-party connectors and integrations require cross-site merging and are not able to take advantage of concurrent site processing within the same organization. Please note that the resource requirements for concurrent task processing scale linearly with the specified instance count. The example below configures the console to process up to four concurrent tasks across all organizations: ``` RUNZERO_CRUNCHER_INSTANCES=4 ``` ### Custom javaScript The self-hosted runZero Console allows you to include custom arbitrary JavaScript to be executed on the various runZero Console web pages. To use this feature, add your JavaScript to /opt/runzero/etc/custom.js. If this is your first time configuring this feature, the custom.js file will not exist. You will need to create the file custom.js inside the /opt/runzero/etc folder. To enable the feature set the enviroment variable below to your configuration. ``` RUNZERO_CUSTOM_JS=true ``` ### HTTP headers The security headers sent by the runZero Console can be disabled as needed using the following options: ``` # Disable Strict-Transport-Security RUNZERO_DISABLE_HSTS=true # Disable X-Frame-Options RUNZERO_DISABLE_HXFO=true # Disable X-Content-Type-Options RUNZERO_DISABLE_HXCTO=true # Disable X-XSS-Protection RUNZERO_DISABLE_HXXP=true # Disable Referrer-Policy RUNZERO_DISABLE_HRP=true # Disable Content-Security-Policy RUNZERO_DISABLE_HCSP=true # Disable CSRF-Protection RUNZERO_DISABLE_CSRF=true ``` ### API availability The following setting controls whether public APIs are enabled (ex: /health). ``` # Disable all unauthenticated API endpoints (/health) RUNZERO_DISABLE_PUBLIC_APIS=true ``` ### Unofficial CPEs When runZero can successfully fingerprint an asset's operating system, a CPE will be generated. In cases where the NIST database does not contain an official match, runZero will generate an unofficial CPE by default. This behavior can be disabled by setting `RUNZERO_GENERATE_UNOFFICIAL_CPE` to `false`: ``` RUNZERO_GENERATE_UNOFFICIAL_CPE=false ``` When unofficial CPEs are generated by runZero, they include `r0_unofficial` in the `other` field of the CPE by default. This value can be changed to any alphanumeric-constrained tag (limited to 32 characters): ``` RUNZERO_UNOFFICIAL_CPE_TAG=custom_unoffical_tag ``` ### Rewriting `cve.org` URLs In some circumstances, you may want to rewrite links to `cve.org` to an internal mirror or alternative site. This can be achieved in the product UI by using the environment variable `RUNZERO_REPLACE_URL_PREFIX_CVEORG`. For example: ``` RUNZERO_REPLACE_URL_PREFIX_CVEORG=https://cve.mirror.local/cve/ ``` The example given would result in `cve.org` URLS in the product interface being rewritten to `https://cve.mirror.local/cve/$1` where `$1` would be replaced with the CVE identifier, such as `CVE-12345`. ## Permissions The self-hosted platform requires **root** access to install and manage from the command-line. The platform service (`runzero-console`) runs as **root** and spawns a worker subprocess that runs as the **runzero** user account inside of a chroot environment (/opt/runzero). All substantive work happens within this isolated subprocess. Please note that older installations will use `rumble` instead of `runzero` in directory, file, and user names. The following filesystem locations are used by the self-hosted platform: ### /etc/runzero | Path | Owner | Permission | Notes | |---------------------------|-------|------------|----------------------------------------------------| | `/etc/runzero` | root | 0700 | Configuration files and certificates | | `/etc/runzero/config` | root | 0600 | A plain-text configuration file | | `/etc/runzero/certs` | root | 0700 | A directory containing the TLS certificate and key | | `/etc/runzero/certs/cert.pm` | root | 0600 | The TLS certificate in PEM format | | `/etc/runzero/certs/key.pm` | root | 0600 | The TLS certificate private key in PEM format | ### /opt/runzero {.pagebreak} | Path | Owner | Permission | Notes | |----------------------------------------|--------|------------|-----------------------------------------------| | `/opt/runzero/tmp` | runzero | 0755 | A temporary directory | | `/opt/runzero/storage` | runzero | 0700 | Contains asset and scan artifacts | | `/opt/runzero/console` | root | 0755 | Contains the platform executable | | `/opt/runzero/console/runzero-console.bin` | root | 0755 | The platform executable | | `/opt/runzero/agent` | root | 0755 | Contains the Explorer binaries | | `/opt/runzero/agent/runzero-agent-*` | root | 0755 | The Explorer binaries | | `/opt/runzero/scanner` | root | 0755 | Contains the CLI binaries | | `/opt/runzero/agent/runzero-scanner-*` | root | 0755 | The CLI binaries | | `/opt/runzero/proc` | root | 0755 | Contains copies of system /proc files | | `/opt/runzero/proc/cpuinfo` | root | 0644 | A copy of /proc/cpuinfo | | `/opt/runzero/proc/meminfo` | root | 0644 | A copy of /proc/meminfo | | `/opt/runzero/proc/version` | root | 0644 | A copy of /proc/version | | `/opt/runzero/etc` | root | 0755 | Contains copies of system files | | `/opt/runzero/etc/resolv.conf` | root | 0644 | A copy of /etc/resolv.conf | | `/opt/runzero/etc/hosts` | root | 0644 | A copy of /etc/hosts | | `/opt/runzero/etc/ca-certificates.crt` | root | 0644 | A copy of the system root CA store | | `/opt/runzero/etc/runzero` | runzero | 0700 | Contains instance identifiers | | `/opt/runzero/etc/runzero/cruncher.id` | runzero | 0700 | A unique ID to identify the cruncher instance | | `/opt/runzero/etc/runzero/hub.id` | runzero | 0700 | A unique ID to identify the hub instance | | `/opt/runzero/config` | root | 0700 | Unused today | ## Backup and restoration Your runZero installation and data can be backed up and restored to preserve your configuration. ### runZero data backup A backup of a self-hosted installation can be obtained by archiving the file system and database. The file system archive includes the following paths: - `/etc/runzero` - `/opt/runzero` - `/lib/systemd/system/runzero-console.service` - `/etc/systemd/system/multi-user.target.wants/runzero-console.service` - `/usr/bin/runzeroctl` A sample file system backup command is: ```bash # tar zcvf runzero-backup-fs.tar.gz /etc/runzero/ /opt/runzero/ \ /lib/systemd/system/runzero-console.service \ /etc/systemd/system/multi-user.target.wants/runzero-console.service \ /usr/bin/runzeroctl ``` The PostgreSQL database must be backed up separately. A sample command is shown below: ```bash # sudo su - postgres $ pg_dumpall -f runzero.sql && gzip runzero.sql ``` ### runZero data restoration To restore the runZero install, follow these steps. 1. Stop any running runZero service: ```bash # runzeroctl stop ``` 2. Unpack the filesystem archive: ```bash # tar -C / -zxvf /path/to/runzero-backup-fs.tar.gz ``` 3. Restore the PostgreSQL database: ```bash # sudo su - postgres $ dropdb runzero; gzip -dc runzero.sql.gz | psql ``` 4. Restart the runZero service: ```bash sudo systemctl restart runzero-console ``` ## Support and debugging The `runzeroctl` command includes a debugging tool which can collect diagnostics from your server and assemble them into a zip file which you can send to support. If you are asked to do this, the command is: ```bash runzeroctl diagnostics run-script ``` Data is written to `/opt/runzero/collector`. Alternatively you can save a copy of the script to the current directory so that you can examine it before running it: ```bash runzeroctl diagnostics write-script ``` ## Manual migrations Starting with version `4.0.240221.0`, the runZero self-hosted upgrade process will run migrations before restarting the service. If you are running an older version of the software and would like to prevent downtime during the upgrade of a single-node self-hosted installation, the following steps can be used: 1. Obtain the self-hosted download link from the [runZero SaaS](https://console.runzero.com). 2. Download this file manually to your self-hosted systems: `$ curl -o platform.bin https://console.runzero.com/....../runzero-platform.bin` 3. Mark this file as executable and run it with the `task db:migrate` parameter: `$ chmod u+x platform.bin; ./platform.bin task db:migrate` 4. Once the migrations are done, install the update as usual: `$ runzeroctl update` --- docs/self-hosting-offline.md --- title: "Offline mode configuration" --- ## ((Offline installation|offline installation)) {#offline-install} The self-hosted runZero platform comes with a few options for your installation. You can utilize these options by adding flags to the install command. The current flags available are `--offline`, `--postgres-version`, `--distro-packages-only`, and `--postgres-rpm-directory`. `--offline` : Configures the installation for operation without internet access. Network access may still be necessary during the installation to acquire dependencies. The installer uses the upstream postgresql.org packages by default and this can be disabled by specifying the options below. `--postgres-version` : Specify a particular major version of PostgreSQL (14-18). If your operating system does not include the default version of PostgreSQL (18), you may need to use the PostgreSQL.org packages instead, which may include downloading them ahead of time for an offline installation. `--distro-packages-only` : Install the platform without using third-party repositories. The install will try to acquire the PostgreSQL package from the configured operating system repositories (local or remote). If no repository is reachable, these packages can also be specified as a directory on the file system using the option below. Note that OS packages may be limited to older versions of PostgreSQL. `--postgres-rpm-directory [directory]` : Install using supplied ((PostgreSQL)) RPM files (requires RHEL or CentOS). The installer will use the ((RPMs)) in the specified directory to satisfy the PostgreSQL dependencies. By default, the console will be installed to `/opt/runzero`. If you need to change this, you can use the `--install-directory [directory]` option. ### PostgreSQL RPMs required for `--postgres-rpm-directory` **There are four RPMs required for installing PostgreSQL:** - postgresql18 - postgresql18-server - postgresql18-contrib - postgresql18-libs #### x86_64 Intel - [RHEL/CentOS 10 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-10-x86_64/). - [RHEL/CentOS 9 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-9-x86_64/). - [RHEL/CentOS 8 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-8-x86_64/). #### 64-bit ARM - [RHEL/CentOS 10 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-10-aarch64/). - [RHEL/CentOS 9 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-9-aarch64/). - [RHEL/CentOS 8 RPMs](https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-8-aarch64/). ### Example install commands for offline mode The first step is to download the [runZero platform](https://console.runzero.com/deploy/download/platform) #### RHEL/CentOS 8, 9, or 10 1. Download the required RPMs above and store them in a directory. 2. Run this install command as root: ```bash ./runzero-platform-[VERSION]-linux-amd64.bin install --offline --postgres-rpm-directory [RPM_DIRECTORY] --postgres-version=18 ``` #### Ubuntu 18.04+, Debian 10+, or RHEL/CentOS 8, 9, or 10 1. Run this install command as root. ```bash ./runzero-platform-[VERSION]-linux-amd64.bin install --offline --distro-packages-only ``` Remember to use `su -` on Debian, not just `su`.
Note
Some components of the application still reference the name "Rumble" for backwards compatibility. The documentation will be updated as these are changed.
## Enabling offline mode for existing installs - Open `/etc/runzero/config` with an editor of your choice. - Look for `OFFLINE=` and change it to `OFFLINE=true`. - Restart the runZero service `runzeroctl restart`. ## CLI update with offline mode {#offline-update} The self-hosted runZero platform must be updated prior to first use. ### Update the runZero platform and scanners with an offline update - Go to [https://console.runzero.com/deploy/download/platform](https://console.runzero.com/deploy/download/platform). - Copy the command directly from the download page and run it in your terminal, or you can use one of the following commands to update using the zip archive you downloaded. ```bash runzeroctl update runzero-platform-update-[VERSION].zip ``` ```bash runzeroctl update --offline --zip-file-path runzero-platform-update-[VERSION].zip ``` You will need to change the version to match the zip archive you downloaded. --- docs/self-hosting-ha.md --- title: "High-availability configuration" aliases: ["/docs/self-hosted-ha/"] --- Self-hosted installations of runZero can be configured for ((high-availability)). For this configuration, a load balancer is used to direct traffic to multiple console servers, which use a shared PostgreSQL cluster and storage backend. The following diagram illustrates an example architecture of a high-availability installation using AWS with two availability zones. ![Self-Hosted HA Architecture](img/self-hostedHA.svg) In this diagram, an application load balancer (ALB) is terminating TLS and pointing to a target group that consists of two runZero servers, each in separate availability zones. The runZero servers use a multi-availability-zone PostgreSQL RDS instance, also configured for the same two availability zones, and both servers point to the same set of S3 storage buckets. ## Installation steps {#high-availability-install} These are the general steps for installing and configuring a high-availability instance of runZero: 1. [Deploy an application load balancer.](#deploy-a-load-balancer-with-tls-termination) 2. [Install and configure the first server node.](#prepare-the-first-runzero-server-node) 3. [Install and configure subsequent server nodes.](#installing-and-configuring-subsequent-nodes) ## Deploy a load balancer with TLS termination In order to provide a high-availability interface to the runZero cluster, an application load balancer should be used that receives TLS connections and forwards the HTTP requests to the available servers. This load balancer should be highly-available on its own. Any load balancer that can proxy large HTTP requests and websockets should be supported. The load balancer should add an X-Forwarded-For header to the HTTP requests sent onward to the runZero servers. The load balancer should also support detection of unhealthy nodes in order to handle automatic failover. The /health endpoint on the runZero servers can be used to implement health checks on the load balancer. ## Prepare the first runZero server node The general steps for installing and configuring the first runZero node are: 1. Install the runZero platform. 2. Configure the console URL and TLS/XFF settings. 3. Configure the database settings. 4. Configure the shared storage settings. 5. Verify your configuration. 6. Create the initial user account. 7. Add the runZero server to the load balancer and verify the connection. ### Install the runZero platform {#high-availability-first-install}
Note
Some components of the application still reference the name "Rumble" for backwards compatibility. The documentation will be updated as these are changed.
1. Go to [platform download page](https://console.runzero.com/deploy/download/platform) in the runZero Console. 2. Copy the URL to the platform installer from the download page. The download path for the installer is uniquely keyed to your license. 3. Download the install using Wget or cURL: - `wget -O runzero-platform.bin https://console.runzero.com/download/platform-combined//62e41615/runzero-platform-vX.X.X-linux-amd64.bin` - `curl -o runzero-platform.bin https://console.runzero.com/download/platform-combined//62e41615/runzero-platform-vX.X.X-linux-amd64.bin` 4. Run the following command to make the installer file executable: ```bash # chmod u+x runzero-platform.bin ``` 5. Run the install command with the manual database option: ```bash # ./runzero-platform.bin install --manual-database ``` ### Configure the console URL and TLS/XFF To configure your self-hosted installation for high-availability, the settings below should be configured in `/etc/runzero/config`, starting with the console URL and the TLS/XFF settings. - Set RUNZERO_CONSOLE variable to the hostname or IP address of the load balancer: ```bash RUNZERO_CONSOLE=https://{IP ADDRESS OR HOSTNAME}:443 ``` - Disable TLS and configure the server to trust X-Forwarded-For headers with the following two lines: ``` TLS=false RUNZERO_TRUST_XFF=true ``` ### Configure the database The next step is to configure the database to be used by runZero. - To do this, edit the DATABASE_URL value to match this format: ```bash DATABASE_URL=postgres://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?{DB_OPTIONS} ``` An example DATABASE_URL for AWS RDS will look like: ```bash DATABASE_URL=postgres://rumble:[password]@rumbledb.rds-id.us-east-1.rds.amazonaws.com:5432/rumble?sslmode=require ``` To use a replica for read-only queries, specify DATABASE_REPLICA_URL with the same syntax. For RDS Aurora, specify the read-only endpoint as the replica URL. If no replicas are in use, only the DATABASE_URL is required, and this should point to the writer endpoint for RDS Aurora instances. If a different type of PostgreSQL clustering is in use, make sure that the DATABASE_URL points to the highly-available endpoint for the active writer. ### Configure shared storage Next, configure the shared storage backend. This is used for storing asset data, raw scan data, and reports. runZero supports both mounted NFS and object storage. - To use NFS, mount a read-write NFS share to /opt/runzero/storage and specify local storage mode with the following configuration options. The bucket names will be created under the NFS mount base directory. ```bash RUNZERO_STORAGE_MODE=local RUNZERO_STORAGE_PATH=/opt/runzero/storage ASSET_BUCKET=runzero-assets SCAN_BUCKET=runzero-scans ``` - To use AWS S3 as the shared storage, either configure an IAM instance role with read-write access to two S3 buckets, or specify the AWS credentials in the configuration file. - To specify AWS credentials specifically for runZero, use the following syntax: ```bash AWS_ACCESS_KEY_ID=AKIA… AWS_SECRET_ACCESS_KEY=[SECRET] ``` - Specify that the S3 storage mechanism should be used and set the name of the two buckets: ```bash AWS_REGION= RUNZERO_STORAGE_MODE=s3 ASSET_BUCKET=-runzero-assets SCAN_BUCKET=-runzero-scans ``` If a non-AWS backend is used that is compatible with the S3 API, use the same AWS and bucket variables above but override AWS_REGION and set the AWS_ENDPOINT_URL_S3 parameter to the endpoint as appropriate. Reach out to runZero support if you run into any issues with the endpoint configuration. In addition the variables above, most [AWS CLI environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) are also available for specific tuning. ### Verify the configuration 1. After saving your configuration file, use this command to verify the self-hosted runZero platform can connect to your database: ```bash sudo runzeroctl database verify ``` 2. Once your settings are configured and verified you can restart the self-hosted runZero platform service: ```bash sudo systemctl restart runzero-console ``` ### Create the initial user account - Use the `runzeroctl initial ` command to create the initial user account. ### Add the runZero server to the load balancer and verify the connection - Point the load balancer to the new runZero server's IP on port 80 (unless modified). - Browse to the load balancer URL over HTTPS using the configured DNS name. - Verify that the user account configured previously can authenticate correctly. ## Installing and configuring subsequent nodes - Download and install the runZero platform binary on each node as above with the `--manual-database` option specified. - Copy the configuration file from the first node to `/etc/runzero/config` on each subsequent node. - After saving your configuration file, use this command to verify that the self-hosted runZero platform can connect to your database: ```bash sudo runzeroctl database verify ``` - Restart the platform service by running: ```bash sudo systemctl restart runzero-console ``` runZero nodes should be spread across multiple availability zones and added to the load balancer's target group. Verify that requests are reaching each individual node by reviewing the syslog entries on that node. ## AWS advanced configuration {#high-availability-s3} AWS Secrets Manager can be used to retrieve configuration settings at startup. The Secrets Manager entries should match the key names of the configuration file. The secret name can be defined with: ``` AWS_SECRETS_MANAGER_KEY=rumble/production ``` To ensure that runZero can access the Secrets Manager, ensure that an AWS_REGION is set in the configuration file, and that the instance has an IAM instance role with permission to read the Secrets Manager key or the AWS credentials have been specified directly in the configuration file. With a Secrets Manager configuration, only the AWS options need to be present in the configuration file and the rest of the settings will be loaded from the Secrets Manager key. This will require copying and defining various settings from the generated configuration file to the Secrets Manager key-value pairs. Note that many settings need to be identical across the runZero cluster for web requests and authentication to work correctly (including session secrets, DB encryption key, and the console URL). --- docs/self-hosting-collection.md --- title: "Self-hosted troubleshooting" --- The runZero console includes a ((diagnostics collection)) script inspired by the need to troubleshoot a self-hosted environment. Collecting the necessary performance statistics, log files, system configuration, and profile debug capture was difficult for customers since there are many different commands and files involved. After checking permissions and dependencies, the diagnostic script gathers and compresses troubleshooting data into a convenient archive file that can be provided to runZero support. The script provides a consistent method for data collection whether it be from a system running your self-hosted console or an Explorer. ## Requirements {#self-hosted-troubleshooting-requirements} The diagnostic script must be run from a Linux system. Additionally, the following dependencies must be installed for the script to run successfully: | Dependency | To install (Ubuntu) | To install (RHEL, CentOS, Fedora, Oracle Linux) | |------------|-----------------------|-------------------------------------------------| | `zip` | `apt install zip` | `dnf install zip` | | `unzip` | `apt install unzip` | `dnf install unzip` | | `lsscsi` | `apt install lsscsi` | `dnf install lsscsi` | | `iostat` | `apt install sysstat` | `dnf install sysstat` | | `curl` | `apt install curl` | `dnf install curl` | The script must be run as `root` or with `sudo` in order to gather information from the system files and the `/opt/runzero` and `/etc/runzero` directories. ## Running the script {#self-hosted-troubleshooting-script} ### Using runzeroctl To run the script via the `runzeroctl` command, use: `runzeroctl diagnostics run-script` Output will be placed in `/opt/runzero/collector`. ### Manually To run the script manually, use the command below to write a copy of the script to the current directory: `runzeroctl diagnostics write-script` The script will be written as `runZero-collector.sh`. To run it: `sudo ./runZero-collector.sh` The script also has a `--help` option. This script will perform the following tasks: * Check for the required permissions. * Check for the dependency commands (lsscsi / zip / unzip/ iostat / curl). * Check that the operating system is Linux. * Check that either a runZero Explorer or runZero console is installed. * Collect system configuration information. * Collect system performance statistics. * Collect database configuration information. * Collect some basic statistics from the database. * Collect runZero debug information from the console or log files from the Explorer. * Create a zip file of the data collected and the log from the script. ## Logging {#self-hosted-troubleshooting-logging} The script will log all actions in `/tmp` and will provide the file name. Upon completion the log file is moved to the `/opt/runzero/collector` directory. This directory does not exist with the installation of a runZero Explorer or runZero console. The script will create the directory if it doesn't exist and place all files into that directory. --- docs/data-retention.md --- title: "Data retention" --- runZero allows the ((data retention)) periods to be configured at the organization level. The organization settings page provides three ways to control how runZero manages your asset and scan data. Data expiration is processed as a nightly batch job based on the current settings for each organization in your account. By default, data is retained for up to 1 year in the runZero Platform. This can be increased to up to 3 years for active subscriptions. The runZero Community Edition is limited to 30 days of retention. ## ((Stale asset expiration)) Stale asset expiration allows you to make sure that out-of-date information gets purged from runZero. Assets which have not been seen in the specified number of days are automatically deleted. The automatic deletion task runs once per day. The stale asset expiration limit applies to both online and offline assets. For example, if an asset was online when last scanned, but hasn't been scanned (or imported via a connector) in the specified number of days, then the information is stale and the asset will be deleted. It's like running an asset search query of `last_seen:>Xdays` (where X is replaced by a number), and deleting the resulting assets. Stale asset expiration can be set at both the Organization and Site levels. The lower value will be used. You can disable stale asset expiration by setting the number of days to zero. ## ((Offline asset expiration)) Offline asset expiration allows you to clear out information about assets that no longer exist on the network. Assets which are offline and have not been seen in the specified number of days are automatically deleted daily. Online assets are not touched. The automatic deletion task runs once per day. This feature is particularly useful for guest wireless networks, or networks with short DHCP leases. It's like running an asset search query of `last_seen:>Xdays AND alive:false` (where X is replaced by a number), and deleting the resulting assets. You can disable offline asset expiration by setting the number of days to zero. ## ((Stale integration attribute expiration)) Stale integration attribute expiration allows you to clear out data from integrations that are no longer reporting an asset. Attributes for assets that have not been reported by the integration in more than a specified number of days are automatically deleted. Assets with no remaining data sources are also removed. The automatic deletion task runs once per day. Optionally, you can keep the latest attribute set per integration, even if it is older than the specified threshold. You can disable stale integration attribute expiration by setting the number of days to zero. ## ((Stale vulnerability expiration)) Stale vulnerability expiration allows you to remove out-of-date vulnerability data. Vulnerabilities that have not been updated in more than a specified number of days are automatically deleted. The automatic deletion task runs once per day. You can disable stale vulnerability expiration by setting the number of days to zero. ## ((Scan data expiration)) This setting controls how long runZero will retain the raw data and metadata for Scan and Import tasks. If your organization has a maximum data retention policy for cloud services, this setting can be used to force the removal of any data older than a given number of days. The default setting of 365 preserves one year of historical scan data. ## ((Event records)) Account-level event records (found under Alerts -> Events) are always retained for one year. If you need to keep copies of these for longer than one year, these records can be exported and archived through the API. ## ((Data deletion after account termination)) Upon termination of your runZero Platform subscription, your data will be deleted according to the table below. | Data Type | Default | Maximum | |-----------|---------|---------| | Stale assets (devices that have not received any new data from active, passive, or integration tasks) | 180 days, unless requested earlier by emailing support[at]runzero.com | 3 years (solely as set by you in runZero Platform prior to account termination) | | Task data (raw data associated with each discovery task) | 1 year, unless requested earlier by emailing support[at]runzero.com | 3 years (solely as set by you in runZero Platform prior to account termination) | | All other data (including data contained in support tickets, administrative data, etc.) | Upon written request by you to runZero at support[at]runzero.com | n/a | | Any of the above data types archived as a copy on backup systems | 1 year from date original data point is deleted | n/a | If you downgrade from your runZero Platform subscription to the free Community Edition, your data will be deleted according to the table below. | Data Type | Default | Maximum | |-----------|---------|---------| | Stale assets (devices that have not received any new data from active, passive, or integration tasks) | 30 days, unless requested earlier by emailing support[at]runzero.com | 3 years (solely as set by you in runZero Platform prior to account termination ) | | Task data (raw data associated with each discovery task) | 10-30 days, unless requested earlier by emailing support[at]runzero.com | 3 years (solely as set by you in runZero Platform prior to account termination ) | | All other data (including data contained in support tickets, administrative data, etc.) | Upon written request by you to runZero at support[at]runzero.com | n/a | | Any of the above data types archived as a copy on backup systems | 1 year | n/a | --- docs/managing-your-team.md --- title: "Managing access" --- runZero supports multiple concurrent users with a variety of ((roles)). Roles can be set per-user on both a default and per-organization basis. The standard roles are administrator, user, billing, annotator, viewer, and no access. There is also a superuser role available to manage global settings. Where there are multiple roles defined for a user, the access granted is based on most privilege. For example, if a user has user access by being in a group, but admin access assigned directly, they will be given admin privileges. ## Available roles ### Superuser The first user created within the runZero console is considered a ((superuser)). This role allows management of global settings like subscriptions and SSO parameters, and is shown as an access level of "everything". If you are a superuser, you can promote someone else to be a superuser. To do this, check the row listing them, and click the _Promote to superuser_ button. If you are using [SSO authentication](implementing-sso.md), you should configure at least one superuser with a strong password and MFA that can used as a backup if SSO settings need to be changed in the future. We strongly recommend having more than one superuser, particularly if you are using MFA. That way if an MFA token is lost or a superuser leaves your organization, another superuser can fix the problem. ### Administrator ((Administrators)) can modify any aspect of an organization and have the unique ability to permanently delete bulk data, create additional organizations, and reset settings for other users. ### User Users have full access to an organization and can update sites, modify assets, schedule scans, and generally use most functionality. Users are not permitted to reset other users' security credentials, bulk delete data, or delete an organization. ### Billing ((Billing)) users are unable to see any asset data, but can manage the licensing, billing, and entity settings for the account. ### Annotator ((Annotators)) have the same permissions as a viewer, except they have the ability to add tags to assets. Annotators do not have any other write-access within an organization, so they are unable to modify or remove existing tags. Modifications to existing tags must be made by a runZero user or administrator. ### Viewer ((Viewers)) have read-only access to an organization. This includes inventory data, findings, queries and reports. Viewers are not allowed to interact with tasks, modify settings, or update assets. Viewers cannot install explorers or download the CLI scanner nor do they have access to client API tokens or organization level API tokens. Certain reports cannot be generated by Viewers, including the Organization overview report, the External assets report and the Organization and site comparison report. However, previously generated versions of these reports will be visible. ### No Access The _no access_ role is generally used as a default. Accounts with ((no access)) as a default are limited to those organizations where they have been granted access. If no organizations are allowed, the user is limited to managing their own account settings. The no access global role can be used to create a single-organization user, such as a customer or third-party that needs access to the inventory for a specific organization. For consulting use cases, a single-organization user is a way to provide clients with visibility into their environment at no additional cost. Another use for the _no access_ role is to set it as the default for the account when you have no limits on who can sign in using an SSO system. You can then wait for the user to sign in and request access, before granting their newly-created account access to the appropriate organizations. ## Inviting users To add a ((team member)), access the [Your team](https://console.runzero.com/team) page, and use the _Invite user_ button to send an invitation. The **Your team** menu entry has several submenus. - The first, _Users_, shows all users in the current client account. - The second entry, _Restricted_, goes to a page listing users who by default have no access to any organization. - The next entry is the name of the current organization, as selected from the organization selector at the top of the screen. The page shows only users with access to that organization. - The _External_ entry goes to a page where you can invite users from other runZero client accounts. - Finally, _Groups_, lists the [user groups](managing-user-groups.md) available. Groups can be used to set access and permissions users have within each organization. ## User details On the Users page, you can click on a user to view their details page. The user details include a list of their effective access to each organization. These details are split into three sections: - _User access_ lists access to organizations that has been directly granted to the user. - _Group access_ lists access to organizations that they are granted because they are in a group that has access to the organization. - _SSO group access_ similarly lists access from being in a group, but in this case for groups set as a result of [SSO group roles](implementing-sso.md). Directly assigned user permissions can be edited using the gear icon button, either at the right side of the appropriate row of the user listing, or using the button at the top right of their user details page. While editing user permissions using the gear icon, you are editing the explicit assigned roles. To see the resulting access levels, check the user details page. ## Account settings {#account-settings} The _Account_ page is available to superusers. It contains settings which apply to all users and organizations within the account. ### Single-sign on (((SSO))) {#sso-settings} runZero supports the [implementation of SSO](implementing-sso.md) through SAML2. If you use a SAML2-compatible single sign-on (((SSO))) implementation, the [SSO Settings](https://console.runzero.com/team/sso/idp/) page can be used to configure an Identity Provider (IdP) and allow permitted users to sign in to the runZero console. ### Multi-factor authentication (((MFA))) {#mfa-settings} runZero supports ((multi-factor authentication)), also known as ((two-factor authentication)) or ((2FA)). Physical hardware keys such as [Google TitanKey](https://cloud.google.com/titan-security-key/) and [Yubico YubiKey](https://www.yubico.com/store/) are supported via the [WebAuthn](https://webauthn.guide/) standard.
Note that the WebAuthn standard does not support use of an IP address as the relying party identifier. As a result, you cannot configure multi-factor authentication on a self-hosted console unless you are accessing the console using a domain name.
You can configure MFA policies for your account via the [Account settings page](https://console.runzero.com/account). If multi-factor authentication is required, users who do not have an MFA token set up will be required to set one up when they next sign in. You can choose between requiring this for all users, or only requiring it for non-SSO users. The latter option is useful if your SSO server enforces MFA use. Once a user registers one or more MFA tokens, they will be required to use one of the tokens every time they sign in. Note that **changing the account settings to not require MFA will not alter the MFA status of existing accounts**. Existing accounts will keep any existing MFA tokens they have registered, and will still be required to use one to sign in. To disable MFA for a user, the user must clear the MFA token registration. To do this, they can go to their [user settings page](https://console.runzero.com/settings) and click the red "Unlink" text next to the token ID in the bottom right. ### Disabling support access {#disabling-support} If you check the box labeled _Disable support access to your account_, runZero support staff will not be allowed to switch to your account. If you choose to disable support access, this may make it harder for runZero support to answer any questions you have. In some cases we may need you to turn support access back on so that we can help you. ### Idle times and sign in duration {#session-timeout} You can set a maximum idle session time in minutes. If set, users whose web browsers don't access runZero for the specified time period will be considered idle, and signed out. You can also specify a maximum sign in duration. If set, users will be forced to sign in again regularly, at least once every specified period. ### Account API keys {#account-api-keys} The ((Account API)) is a REST API which allows account-level operations such as adding and removing organizations and sites, adding users, and accessing the system event log. The _Generate API Key_ button on the Account page can be used to generate a token which will allow access to the Account API. ### License information {#license-info} The _License_ page shows information about your runZero software license, including how many assets you are licensed for, how many assets you have across all organizations, and when your license renews. ### Entity information {#entity-info} The _Entity_ page allows you to update information about the legal entity runZero is licensed to. You should ensure that this information is kept up-to-date if your company changes name or location, as we use the information to calculate taxes and ensure compliance with appropriate regulations. ### Audit log {#audit-log} The _Audit log_ page shows a history of all system events relevant to the superuser, such as login events, that are not visible within the organization Events page. --- docs/managing-user-groups.md --- title: Managing user groups --- ((User groups)) help streamline the management of users who need the same set of permissions. A user group explicitly sets the organizational [role](managing-your-team.md) for users, which determines the tasks they can perform within each organization. You can assign roles at a per-organization level or assign a single role across all organizations. Single sign-on settings can also be applied to groups through [SSO group mappings](managing-sso-group-mappings.md).
What happens if there are conflicting permissions?

runZero will always grant the role with the highest permissions level. For example, let's say an account has a viewer role for all organizations, but they've been added to a user group that has a user role for all organizations. This user will now have user-level permissions for all organizations. If the user group expires, the user's role reverts back to their account-level role.

User groups can also have an optional expiration date, which sets time-bound access to organizations within runZero for specific users. When the expiration date elapses, the user reverts back to their account-level permissions. If no expiration date is set, the user group settings will be persistent. ## Creating user groups runZero administrators and super users can create user groups. 1. Go to [Your team > Groups](https://console.runzero.com/groups/new) and click Add Group. 2. Enter a name for the user group. 3. Choose the default role you'd like to assign to the group. This setting will establish the access level for every organization you have. 4. Set the per-organization roles, if you need to provide different access levels to specific organizations. 5. Set an expiration date for the user group, if you need to time-bound the permissions. When the expiration date elapses, the role for users part of the group will revert back to their user-level permissions. Otherwise, if you don't specify an expiration date, the user group will be persistent. 6. Go to the **Add users** tab and search for the users you want to add to the group. You can search by username or email. 7. When you are done adding users, save the user group. The user group will be listed on the [Groups page](https://console.runzero.com/groups). ## Adding users to user groups To add users to multiple groups at the same time, you can use the _Edit group membership_ button on the [Users page](https://console.runzero.com/team/). The _Edit group membership_ window will list every user group each user is currently in. Making changes from the _Edit group membership_ window will apply to all users you have selected. Only runZero administrators and superusers can add users to user groups. 1. Go to the [Users page](https://console.runzero.com/team/). 2. Select the users you want to add to a group. 3. Click the **Edit group membership** button. 4. Choose the user groups you want to add the users to. 5. Save your changes. ## Setting an expiration date for a user group runZero administrators and super users can set an expiration date for a user group. 1. Go to [Your team > Groups](https://console.runzero.com/groups/). 2. Find the user group you want to assign an expiration date. Click the name to open the config page. 3. Set an expiration date for the user group. After the expiration date, the user's role will revert back to their account-level permissions. 4. Save the user group. You'll be able to see the user group's expiration date from the [Groups page](https://console.runzero.com/groups). ## Viewing users in a user group 1. Go to [Your team > Groups](https://console.runzero.com/groups/). 2. Find the _Users_ column in the _User groups_ table, which shows the user count for the group. 3. Click the user count to query and display the users assigned to the group. ## Viewing user groups assigned to a user 1. Go to [Your team > Users](https://console.runzero.com/team/). 2. In the Groups column for each user is the number of groups that user is a member of. 3. Click on a number to show the corresponding list of groups. ## Removing users from a user group runZero administrators and super users can remove users from a user group. 1. Go to [Your team > Groups](https://console.runzero.com/groups/). 2. Find the user group you want to modify. Click the name to open the config page. 3. Go to the _Users_ tab. 4. Remove the users you no longer want assigned to the group. Their permissions will revert back to their account-level ones. 5. Save your changes. ## Deleting user groups runZero administrators and super users can delete user groups. 1. Go to [Your team > User groups](https://console.runzero.com/groups/). 2. Select the user group you want to delete. 3. Click the **Delete** button. 4. Confirm you want to delete the user group. ## Searching for users and user groups When you are on [Users page](https://console.runzero.com/team/) or [Groups page](https://console.runzero.com/groups/), you can use the following keywords to search in the table: | Keyword | Description | Example | |--------------|----------------------------------------------------------------------------------------------|--------------------| | `id` | User's ID. | `id:123456789` | | `name` | User's name. | `name:john` | | `expires_at` | [Time or date](search-query-syntax.md/#time-and-date-values) the user group expires. | `expires_at:>2weeks` | | `created_at` | [Time or date](search-query-syntax.md/#time-and-date-values) the user group was created. | `created_at:>2weeks` | | `updated_at` | [Time or date](search-query-syntax.md/#time-and-date-values) the user group was last updated.| `updated_at:>1year` | | `has_expiration` | Whether the group has an expiration date. | `has_expiration:true` | | `created_by_id` | ID of user who created the user group. | `created_by_id:123456789` | | `created_by_email` | Email of the user who created the user group. | `created_by_email:user@example.com` | | `group_id` | The user group ID. | `group_id:123456789` | | `group_name` | The user group's name. | `group_name:group1` | Group IDs can be found in the URL for the group config page `https://console.runzero.com/groups//edit`. The `group_id` keyword is only available for the users table; for the groups table, use `id`. --- docs/bulk-importing-users.md --- title: Bulk importing users --- Instead of manually adding users one at a time, runZero administrators can ((add multiple users)) via bulk import. To ((bulk import users)), you will need to create a CSV (comma separated values) file that contains the user information, such as their first name, last name, email, role, and organizational access. Bulk imports will only add new users; it will not update existing users. If the file contains a user that already exists in the system, the import will not complete. You'll need to remove all duplicate users from your CSV file and import the file again. Here are the high-level steps for bulk-importing users: 1. [Create a CSV file](bulk-importing-users.md#creating-the-csv-file-for-importing-users) with your user information. 2. [Import the CSV file](bulk-importing-users.md#importing-users-into-runzero) into runZero. 3. [Verify users have registered](bulk-importing-users.md#verifying-users-have-registered) their accounts. ## Creating the CSV file for importing users To create the CSV file, you can use the provided [template](https://console.runzero.com/team/templateCSV) or create a file from scratch. You'll need to follow the guidelines and include the fields outlined below. * The first row of the CSV file is the header row and it must be included in the file. It contains the required fields needed for importing users, and those fields must follow a specific order (`first_name`, `last_name`, `email`, `all_orgs_role`, `org_roles`). * runZero requires the `first_name`, `last_name`, and `email` fields. The organization-level fields, `all_orgs_role` and `org_roles`, are optional. * To define the `org_roles` field, use the following format: `orgName=role`. You can use pipes to separate multiple definitions. * Excluding the `all_orgs_role` field from the CSV will result in users being assigned a no-access role in all organizations. * Excluding the `orgs_role` field from the CSV will result in users being assigned the role defined in the `all_orgs_role` field. If both fields are excluded from the file, all users will be assigned the no-access role. They will need to contact the runZero administrator to modify their account access. ### User fields for the CSV file The following table lists the fields you can include in your CSV file: | Field | Description | Example | |-----------|-----------------------------------------|----------------------------| |`first_name` | The user's first name. | `sarah` | |`last_name` | The user's last name. | `smith` | |`email` | The user's email address. | `ssmith@company.org` | |`all_orgs_role` | The role assigned to the user for all organizations. This is optional. | user | |`org_roles` | The role assigned to the user for a specific site. Use pipes to separate the organizations. This field is optional. | org1=user | Your resulting CSV file should look like the following example: ``` first_name,last_name, email,all_orgs_role,orgs_role Sarah,Smith,ssmith@company.org,user,org1=annotator|org2=annotator ``` ## Importing users into runZero 1. Go to your [Team Import](https://console.runzero.com/team/import/) page. 2. Choose the CSV file that contains your user information and upload it to runZero. 3. Import the file. runZero will alert you if there are issues with your file. For example, if the file contains an existing user, the import will not complete. You'll need to remove all duplicate users from your file and import it again. ## Verifying users have registered After you add new users via import, each user receives an email invitation to join your team. The email contains a link to register their email address, which prompts them to enter their name and password for their account. After they create an account, they'll be able to sign in to the runZero console. You can visit the [Teams](https://console.runzero.com/team) page to find the status and last sign in for each user. Users who have completed the registration process will show an _Activated_ status. --- docs/inviting-external-users.md --- title: "Managing external users" --- You can invite ((external users)) to join your runZero instance and view the organizational data available to them. The ability to add external users is useful for consultants, value-added resellers, and managed service providers who want to be able to share data from runZero with external partners and clients. If you are a superuser, you can invite any user who has a runZero account to join your account. When you invite the user, they will receive an invitation to join your account via email. After they accept the invitation and sign in to runZero, they will see a new menu next to their organization switcher that lists all the clients they can access. Your client name will display in the list.
Note
If the person you want to invite does not have a runZero client account, they will need to sign up for one before you can invite them as an external user. A free runZero Community Edition account can be invited as an external user.
External users are only viewable from the [External users page](https://console.runzero.com/team/external), separate from your other user lists. These users can use their same credentials to sign in and switch between clients and the organizations they've been granted access to. ## Inviting an external user into your account 1. Go to **Your team > External** and click [Invite external users](https://console.runzero.com/team/external/invite/). 2. Assign the default role you want to assign the user for all organizations. 3. Enter the email address for the user. The user must have an existing runZero account. 4. Customize access for the user at the per-organization level. runZero grants the highest permission levels, when there is a conflict between the global and per-organization permissions. 5. Add a custom email subject or body, if needed. runZero uses a default email template that informs the user you have invited them to your account and provides a link to activate the invitation. The email sender will be your name and the subject line will be "Invitation to join [client] by [your name]." 6. Send the email. After they activate their invitation, they will be able to sign in to runZero, switch clients, and view your organizational data. ## Switching clients and organizations as an external user External users who have access to another account will see a client switcher, or client dropdown menu, located next to their organization switcher at the top right of the runZero web interface. Changing the client will change the organizations you can access and view. The account that granted you access has configured the organizations and permissions you have within the client account. ## Removing an external user from your account Removing an external user from your account will remove their access to your data. The user will no longer be able to choose your client. To remove an external user, go to the [External users page](https://console.runzero.com/team/external), select the user account you want to remove, and click **Remove user account**. Confirm you want to remove the user. They will be reverted to their primary client account and will no longer have the option to access your runZero data. --- docs/implementing-sso.md --- title: "Implementing SSO" --- If you use a SAML2-compatible single sign-on (((SSO))) implementation, the [SSO Settings](https://console.runzero.com/team/sso/idp/) page can be used to configure an SSO Identity Provider (IdP) and allow permitted users to sign in to the runZero console. runZero's SSO implementation is designed to work with common ((SAML)) providers with minimal configuration, but there are a few requirements: - Your users need to authenticate to a single domain such as `example.com`, not to multiple domains or a domain with many subdomains. - The domain name needs to be configured in the SSO identity provider settings in runZero. This is true even for self-hosted runZero deployments. - Your SAML IdP should provide something that looks like an email address in the standard ((NameID)) parameter. It doesn't need to be a valid email address, but it should be a unique value that has the same syntax as an email address (`user@example.com`). The field name `NameID` is case sensitive. - If the `NameID` does not look like an email address, runZero will check the fields `email`, `user.email`, `emailaddress` and `email address` for a suitable ID. These field names are not case sensitive. - runZero will check for the user's full name in the fields `name`, `gecos`, `user.name` and `displayname`. If no full name field is found, runZero will proceed to check for a first name in `first_name`, `firstname`, `given_name`, `user.firstname`, `givenname` or `first name`; and for a last name in `last_name`, `lastname`, `family_name`, `user.lastname`, `surname`, `sn`, or `last name`. These field names are not case sensitive. Note that you must be [a superuser](managing-your-team.md#superuser) to manage runZero SSO settings.
Note
Once a user logs in using SSO, they can no longer login with a password, even if they were previously able to use a password. For this reason, we strongly recommend that you set up and keep a non-SSO superuser account, so that you can update the settings if SSO stops working for any reason.
## Specific SSO providers You can refer to the [Azure AD](set-up-azure-ad-saml-sso.md) or [Okta](set-up-okta-saml-sso.md) pages for details on configuring these providers. The basic steps for configuration are: 1. Add runZero as an application. 2. Set up SSO in runZero. 3. Provision users to the runZero app. For other SSO providers, the following information will help you to configure things. ## Identity provider settings To get to the identity provider settings, choose _Your team_ from the left navigator, then click the SSO Settings button at the top right of the page. The identity provider settings form is where you enter information about your SSO identity provider. The easiest way to configure SSO is to use XML metadata, if your SSO service provides it. This will usually require that you set up runZero as an application on your SSO provider, then download an XML file. The XML can be then opened in a text editor, and copied and pasted into the box at the bottom of the runZero identity provider settings form. If the XML decodes successfully, the key fields on the form will then be set automatically. ### Single Sign On mode You can choose whether to allow regular runZero accounts, SSO-provisioned accounts, or both. If both are allowed, you can set up backup administrator accounts in case your SSO provider is unavailable. ### Domain name The domain name is used by runZero to locate the correct SSO IdP settings when users choose to sign in via SSO. This is so that it can redirect them to the correct SSO provider to sign in. For example, if the domain is `example.com`, the runZero sign-in page will expect users to begin by entering an address of the form `username@example.com`. The domain is also passed back by the SSO provider after sign in, and used to fetch the SSO IdP settings so that runZero can verify and process the data. The domain is included as part of the ACS URL in the sign in request sent to the SSO provider. If you change the domain, you will need to reconfigure the SSO provider to accept the new ACS URL. ### Issuer URL The issuer URL, also often referred to as the entity ID, is a URL your SSO provider uses to uniquely identify itself in data passed back to runZero. You need to obtain this value from your SSO provider. Note that the value is not normalized to add or remove trailing slashes; it needs to match exactly. ### Sign in URL The sign-in URL is the URL users should be redirected to in order to begin the sign-in process for your SSO provider. ### Certificate The certificate is the PEM encoded CA certificate runZero will use to verify the signature on the data from your SSO provider. If you paste multiple CA certificates into the box, your SSO provider will need to include a `KeyInfo` element in data passed back to runZero, to specify which certificate to check the signature against. ## SSO walkthrough To configure and debug SSO settings, it helps to understand how the SAML sign-in process works. SAML SSO authentication is carried out using messages passed by the user's web browser. No direct connection occurs between runZero and the SSO identity provider (IdP) in either direction. The normal sign-in process starts with the user going to the runZero console sign-in page, choosing **Sign in via SSO**, and entering their email address. The domain name of the email address is used to find the correct SSO identity provider settings in the runZero database. runZero then redirects the user's web browser to the Sign in URL specified in those SSO IdP settings. Some additional parameters are added to the URL, according to the SAML specifications. These are verified by the SSO IdP. The user logs in on the SSO IdP website. The IdP then redirects the user's web browser back to runZero, to the Assertion Consumer URL (ACS URL). The redirection includes a digitally signed blob of encoded data about the authenticated user. The ACS URL is shown on the service provider information tab of the SSO settings. Note that it includes the domain name, so that runZero can find the correct set of SSO settings to use to process the data. runZero then decodes the encoded data, and checks its digital signature using the certificate that was provided as part of the identity provider settings. Assuming the certificate is valid, the decoded information about the user is then trusted by runZero. If necessary, a runZero user account is provisioned. The user is then signed in to begin a new runZero session. ## Service provider information After filling out the identity provider settings, you can switch to the service provider information tab to obtain information you need to provide to your SSO identity provider. The Assertion Consumer URL, sometimes called the SSO URL, is the URL a person's web browser will be redirected to after they sign in successfully on the SSO identity provider. The URL contains the domain that was set up in the identity provider settings. runZero uses the domain to find the right set of SSO settings, so it can verify the data from the SSO provider. This means that if you change the domain in the identity provider settings for any reason, the ACS URL will change, and your SSO provider will need to be given the new URL. The user sign-in URL is a URL that you can visit to begin the sign-in process. It displays the computed identity provider URL to aid in debugging. ## Common problems ### A user signs in on the SSO provider, but runZero refuses the sign in The most common cause of this problem is that the IdP has been configured with an Assertion Consumer URL that does not include the domain name that was set in the SSO identity provider settings in runZero, or includes the wrong domain name. A correct ACS URL will look like `https://console.runzero.com/auth/example.com/saml20/process` where `example.com` is the domain name configured in the runZero SSO identity provider settings. ### Missing x509 Element The full error message is "invalid SAML response: error validating response: Missing x509 Element" This error can occur if you have entered multiple CA certificates into the certificate field of the SSO settings in runZero, but your SSO IdP didn't include a `KeyInfo` element to tell runZero which certificate to check the signature against. You will need to either configure your IdP to include information about which of the CA certificates to use as `KeyInfo`, or use a single CA certificate. --- docs/managing-sso-group-mappings.md --- title: "Managing SSO group mappings" date: 2022-03-08 ---
Only runZero administrators can automatically map users to user groups using SSO attributes and custom rules.
((SSO group mapping)) allows you to map your ((SAML)) attributes to user groups in runZero. In runZero, user groups explicitly set the organizational [role](managing-your-team.md) and determines the tasks users can perform within each organization. When you set up SSO group mappings, you explicitly define the SSO attribute and value you want to use for mapping. If there is a match, runZero will apply the group settings for the user. As a result, you can ensure that SSO users are mapped to their respective groups in runZero. For example, your IT team may need to be part of a group with administrator privileges. In this case, you can create a user group with an administrator role and then create an SSO group mapping that maps the SAML attribute that identifies your IT team to the user group. When someone from your IT team logs in to runZero, they will automatically be added with the appropriate access and permissions, all without pre-provisioning their account. After evaluating all SSO group mapping rules, runZero grants the user the highest privilege assigned for each organization. ## Creating SSO group mappings Before you create your SSO group mapping, make sure that you have [set up SSO](set-up-okta-saml-sso.md) for your organization and [created user groups](managing-user-groups.md). Both must be set up in order to successfully create SSO group mappings. Only runZero super users can create SSO group mappings. 1. Go to [Your team > SSO settings > Group mappings > Add group mapping](https://console.runzero.com/team/sso/groups/new). 2. In the **SSO attribute** field, enter the attribute you want to check for matching values. These values are defined in your SSO configuration. - For Azure AD SSO, note that the **SSO attribute** field must match the claim name from Azure AD. 3. In the **SSO value** field, provide a comma separated list of values that the attribute could match. When there is a match, runZero will apply the group permissions. 4. Click the **Group** dropdown and choose the user group that will be assigned if there is a match. The dropdown will list all user groups that have been created. 5. Save the SSO group mapping. These settings will apply the next time the user logs in to runZero. Changes will not apply to users currently signed in. They will need to sign out and sign back in for the changes to take effect. You can forcibly sign out users to apply the SSO group mappings immediately. ## Forcing a user to sign out Changes to user permissions will not apply until the user signs out and logs back in to runZero. If you need to apply permissions immediately after setting up the SSO group mappings, you can forcibly sign out users. This will sign users out of their current session and require them to sign back in again. After they sign in, their updated permissions will be applied. Only superusers and admins who have access to all organizations can force sign-outs. To forcibly sign out users, go to the [Teams page](https://console.runzero.com/team) and select the users you want to sign out. Click the sign-out button to log these users out. ## Viewing SSO group mappings To view all SSO group mappings that have been created, you can go to the [Group mappings page](https://console.runzero.com/team/sso/groups). From this page, you can create, edit, or delete group mappings as needed. ## Viewing SSO group mapping assignments To see the SSO groups that a user has been assigned to, go to the [Users page](https://console.runzero.com/team). From the _Groups_ column, you can see the number of user groups and SSO groups the user is a part of. The number of SSO groups will be in parentheses. Clicking the gear icon under actions will open the user settings for the user. The access summary tab will then display all of the organizations and roles they have assigned. ## Deleting a group mapping 1. Go to the [Group mappings page](https://console.runzero.com/team/sso/groups). 2. Select the group you want to delete and click the **Delete** button. All users provisioned through the group mapping will revert back to their account-level permissions. ## Searching for SSO group mappings When you are on the [Group mappings page](https://console.runzero.com/team/sso/groups), you can use the following keywords to search in the table: | Keyword | Description | Example | |--------------|------------------------------------------------------------------------------------------|--------------------| | `id` | User's ID. | `id:123456789` | | `sso_attribute` | User's SSO attribute. | `sso_attribute:department` | | `sso_value` | User SSO attribute value. | `sso_value:securityteam` | | `created_at` | [Time or date](search-query-syntax.md#time-and-date-values) user group was created. | `created_at:>2weeks` | | `updated_at` | [Time or date](search-query-syntax.md#time-and-date-values) user group was last updated. | `updated_at:>1year` | | `created_by_email` | Email of user who created the group. | `created_by_email:user@example.com` | | `group_id` | User group ID. | `group_id:123456789` | | `group_name` | User group's name. | `group_name:group1` | Group IDs can be found by going to [the group config page](https://console.runzero.com/groups/) and enabling the ID column from the Columns menu above the data grid. The `group_id` keyword is only available for the Users table; for the groups table, use `id`. The `group_name` keyword is only available for the Users table. --- docs/set-up-azure-ad-saml-sso.md --- title: Setting up Microsoft Entra SSO --- Superusers can configure single sign-on to the runZero Console using an external identity provider (IdP), which enables authentication and user access control to the runZero Console from your single sign-on (SSO) solution. By default, runZero has SSO functionality available, but it's not a requirement to sign in to the console. You can make it a requirement or disable it completely. Here are the high-level steps to set up SSO using Microsoft ((Entra)) (formerly ((Azure AD))) to authenticate and manage user access to runZero: 1. [Add and configure runZero as an Entra app](#step-1-add-and-configure-runzero-as-an-azure-app). 2. [Download the SSO configuration metadata in XML format](#step-2-download-the-sso-configuration-metadata). 3. [Set up SSO in runZero](#step-3-set-up-entra-id-sso-in-runzero). 4. [Add users to your runZero app in Entra ID](#step-4-add-users-to-the-runzero-app-in-azure). ## Requirements {#azure-ad-sso-requirements} Before you can set up SSO for the ((Microsoft Identity Platform)): * Verify that you have administrator privileges for Azure AD. * Verify that you are a [superuser in runZero](https://console.runzero.com/team). Look for the yellow star in your account status. ## Step 1: Add and configure runZero as an Azure app The first thing you need to do is [add runZero as a non-gallery application](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal) to your Azure AD setup and to [configure the settings for runZero](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-configure) as an Azure AD application. 1. In Azure, go to **Enterprise Applications > New Application > Create your own application**. 2. Under the **What are you looking to do with your application?** section, choose the **Non-gallery application** option. 3. Name your application something like `runZero`, and then add it. 4. Go to **Azure Active Directory > Enterprise applications** and open the newly created runZero application. 5. Select the **Single sign-on** tab, and then choose **SAML** as the sign-on method. 6. For the fields on the **Configure App Settings** page, go to https://console.runzero.com/team/sso/sp and copy the necessary service provider details: * Entity ID * Single sign-on URL * SSO callback (ACS) URL 7. Enter the values into the relevant fields in the Azure AD portal. 8. **Do not** set a value for "Sign on URL (Optional)" or "Relay State (Optional)". 9. If you want to use group information from Azure to set up group membership in runZero, [configure the IdP to send group information](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization#add-a-group-claim). ## Step 2: Download the SSO configuration metadata While editing your application settings, you can get the download link to obtain the SSO configuration metadata in XML. You'll need this information to set up SSO in runZero. 1. On the **Configure App Settings** page, find the **SAML Signing Certificate** section. 2. Locate the XML download link under the [Federation Metadata URL](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-saml-single-sign-on#saml-signing-certificate). 3. Download the file. You'll need the contents of this file for the next step. ## Step 3: Set up Entra ID SSO in runZero Now that you have the SSO configuration metadata in XML, you can configure Entra ID SSO settings in runZero. 1. Go to https://console.runzero.com/team/sso/idp to access the SSO IdP provider settings page in runZero. 2. Choose one of the following modes to enable SSO: * **Allowed** - Enables SSO, but users still have the option to sign in without SSO. * **Required** - Requires users to sign in with SSO. Only superusers can sign in without SSO. 3. Enter the domain name that is associated with SSO authentication. This is likely your company domain (companyabc.com). 4. Choose a default role for SSO users. This is the [role](managing-your-team.md) all new users will be assigned when their account is created. 5. Copy the XML you downloaded from Azure and paste it into the Metadata XML field on the runZero SSO IdP page. 6. Apply your SSO settings. The remaining IdP fields will auto-configure for you. * The issuer URL will look something like `https://sts.windows.net/00000000-0000-0000-0000-000000000000/` where the UUID at the end is your unique Microsoft Active Directory (tenant) ID, listed under **App registrations > Overview > Endpoints**. * The sign-in URL will be something like `https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/saml2` with the zero UUID replaced with your unique tenant ID. * The certificate will be Microsoft's PEM encoded certificate, which will be extracted automatically from the XML. * On the Microsoft side, the redirection URL for runZero should be `https://console.runzero.com/auth//saml20/process`, where \ is replaced with the domain specified in the runZero SSO settings. ## Step 4: Add users to the runZero app in Azure Now that you've completed the set up, you can go to the runZero app in Azure portal to [add users and assign their access](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users). Any users you add to the runZero app will be viewable from the [Team members page](https://console.runzero.com/team) in runZero, once they have signed in to runZero. ## Step 5: Update SSO group mappings to match any configured Azure groups (if applicable) If you have created user groups within Azure, you will need to update your [SSO group mappings](managing-sso-group-mappings.md) in runZero to associate the groups created in Azure with user groups in runZero. This will ensure that the appropriate access and permissions are added to your users when they sign in to runZero. When setting up the [SSO group mappings](managing-sso-group-mappings.md), note that the **SSO attribute** field must match the claim name from Entra ID. --- docs/set-up-okta-saml-sso.md --- title: Setting up Okta SSO --- Superusers can configure single sign-on to the runZero Console using an external SAML identity provider (IdP), such as ((Okta)), which enables authentication and user access control to the runZero Console without typing in credentials. Here are the high-level steps to set up single sign-on (((SSO))) using Okta to authenticate and manage user access to runZero: * [Add runZero as an application in Okta.](#step-1-add-and-configure-runzero-as-an-okta-app) * [Set up SSO in runZero.](#step-2-set-up-sso-in-runzero) * [Add users to the runZero app in Okta.](#step-2-set-up-sso-in-runzero) ## Requirements {#okta-requirements} Before you can set up Okta SAML: * Verify that you have administrator privileges for Okta. * Verify that you are a [superuser in runZero](https://console.runzero.com/team). Look for the yellow star in your account status. ## Step 1: Add and configure runZero as an Okta app 1. Go to **Okta > Applications > Create App Integration**. When the **Create a new app integration** window appears, select `SAML 2.0` for your sign-in method. ![Sign-in method](img/okta-saml-option.png) 2. For the general settings, you'll need to provide a name for the app. Call the app `runZero`. You can also add a logo to make it easier for users to identify the runZero app. 3. For the SAML settings, you'll need to go to the [service provider information page](https://console.runzero.com/team/sso/sp) in runZero to find the relevant URLs. * **Single sign on URL** - In runZero, this is the assertion consumer service (ACS) URL. * **Audience URI or SIP Entity ID** - In runZero, the entity ID, or SAML audience, will be `https://console.runzero.com`. * **NOTE:** make sure to include the leading 'https://' when entering this field in Okta. 4. For the remaining settings, like the attribute statements, visit the Okta documentation to [learn how to configure them](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-KnowBe4.html). 5. When you finish configuring the SAML settings, Okta will prompt you for some feedback on how you will be using the app. You can opt to provide feedback or skip to complete the set up. 6. After Okta creates the app, you will need to view the SAML 2.0 instructions to complete the set up. Go to the the **Sign On** tab for the runZero app and view the SAML 2.0 instructions. You'll need these details for the next step. ![Okta SAML instructions](img/okta-saml-instructions.png) ## Step 2: Set up SSO in runZero 1. Go to the [SSO setup page](https://console.runzero.com/team/sso/idp) in runZero. Choose one of the following modes to enable SSO: * **Allowed** - Enables SSO, but users still have the option to sign in without SSO. * **Required** - Requires users to sign in with SSO. Only superusers can sign in without SSO. 2. Enter the domain name that is associated with SSO authentication. This is likely your company domain (companyabc.com). 3. Choose a default role for SSO users. This is the [role](managing-your-team.md) all new users will be assigned when their account is created. 4. Copy the fields from Okta into runZero. * **Issuer URL** - In this field, enter the **Identity Provider Issuer URL** from Okta. This will look something like `http://www.okta.com/` * **Sign-in URL** - In this field, enter the **Identity Provider Single Sign-On URL** from Okta. This will look something like `http:///app///sso/saml`. * **Certificate** - Copy and paste the entire contents of the X.509 certificate from Okta. 5. Apply your SSO settings. ## Step 3: Add users to the runZero App in Okta Now that you've completed the set up, you can go to the runZero app in Okta to [add and manage user access](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-people.htm). After you've completed this step, your users will be able to go to your SSO sign-in URL to access runZero. ## Step 4: Update SSO group mappings to match any configured Okta groups (if applicable) If you have created user groups within Okta, you will need to update your [SSO group mappings](managing-sso-group-mappings.md) in runZero to associate the groups created in Okta with user groups in runZero. This will ensure that the appropriate access and permissions are added to your users when they sign in to runZero. --- docs/managing-licenses.md --- title: Managing licenses description: "How to manage your runZero license and billing" --- As a runZero superuser or billing user, you can access and manage your organization's ((licensing)), plan, and ((billing information)). **Not a superuser or billing user?** Please contact your organization's [superuser or billing user](https://console.runzero.com/team/) to get help with licensing and billing information. These users are tagged with a yellow star. ## How do I view my license? If you're a superuser or billing user, go to [Account > License](https://console.runzero.com/license) to view your runZero licensing information. **Your licensing information will show:** - The number of organizations, sites, Explorers, and user accounts you have. - The number of ((recent assets)) you have across all organizations. - The number of ((project assets)) you have. - The total number of recent assets and project assets your license supports. ## What count as recent assets? runZero calculates the number of recent assets based on how many have been seen during the last 30 days. For assets that have been scanned by runZero, if they have been seen by a scan in the last 30 days, they are counted as recent assets. If third party data indicates a device has been seen in the last 30 days, that will also cause the asset to count as recently seen. License limits are uniform across all asset types. It doesn't make any difference whether the asset is online or offline, scanned or unscanned, or where the asset data was sourced from. For assets with multiple data sources, with different dates that the device was last seen at, the most recent date applies. The number of recent assets is calculated in the background. If you delete assets it may take a short while for the number to recalculate. ## When does my subscription expire? To see when your subscription or license expires, go to [Account > License](https://console.runzero.com/license). Find the line: `This is a runZero [edition] subscription that expires at [date and time].` If your subscription has expired, you will see: `This is a runZero [edition] subscription that expired on [date and time].` You will no longer be able to run discovery scans. To continue using runZero, you will need to [renew your subscription](#how-do-i-renew-my-subscription).
Does the Community license expire? Nope, it's part of our free tier and has no expiration date. You can continue to use it as long as you don't have more than 100 recent assets.
## How do I renew my subscription? For help renewing your subscription, please contact us by [email](mailto:accounts@runzero.com) or by using this [online form](https://www.runzero.com/contact-sales/). ## How do I convert to the Community Edition? No longer need the full platform? You can [convert it to the Community Edition](https://console.runzero.com/license/convert/community). This plan is on our free tier and supports up to 100 recent assets. ## How do I find my invoices? Super users and billing users can access ((invoices)) from the runZero Console. Go to the [License page](https://console.runzero.com/license) to see all invoices. ## How do I change or cancel my subscription? Please [contact us](mailto:accounts@runzero.com) if you need to modify or cancel your subscription. --- docs/gathering-data.md --- title: "Network discovery" --- runZero can gather asset data through unauthenticated ((active scanning)), ((passive)) ((traffic sampling)), and inbound integrations. ## Active scanning The runZero Explorer and scanner perform [unauthenticated active scanning](docs/discovering-assets.md) of your specified networks based on the configurations you set. They leverage various network protocols to discover and fingerprint assets connected to the network. Active scans can be configured to run once or on a schedule. Scan templates can also be used to ensure consistency across multiple scan tasks. ## Traffic sampling Explorers can be configured to perform passive traffic sampling in your environment in order to identify assets communicating across your networks. [Traffic sampling](docs/managing-explorers.md#explorer-traffic-sampling) is configured on a per-Explorer basis on the Explorer details page. Explorers will automatically pause traffic sampling activities in order to handle scan tasks, continuing to parse sniffed traffic once the scan completes. The traffic sampling feature can also ingest a PCAP file to glean useful asset data. ## Inbound integrations [Inbound integrations](docs/integrations-inbound.md) for many different platforms can be configured to enrich your runZero asset context and provide important insights into coverage and capabilities. Integrations can be configured either as connectors or scan tasks. --- docs/discovering-assets.md --- title: "Active scanning" --- An ((active scan)) identifies all responsive devices on a given network, fingerprints these devices, and populates the asset, services, screenshot, and software inventory. Regular scans of internal and external networks is an important step in network management. Scans are configured by site, Explorer, and scan scope. The scan scope can include IP ranges, domain names, ASNs, and even entire country codes. When creating a new scan, you have multiple parameters you can set, ranging from scheduling a date to more advanced options. To get started, login to the runZero Console, select Scan from the Data sources section of the navigation menu, and choose "Start Standard Scan". Scans can also be launched from the Inventory views. ## Site {#discovering-site} runZero organizes information into ((organizations)) and ((sites)). Organizations are distinct entities that are useful for keeping data separate and contain a collection of sites. Sites are used to model segmented networks, particularly independent networks which use the same private IP address ranges. For example, you might have multiple physical locations with their own local networks, all using the 10.0.0.0/8 private IP range. By defining them as sites, you can set up an Explorer for each, and the networks and assets will be treated as completely independent even if similar systems are seen at the same IP addresses in each.
Note
runZero treats each site as a separate IP space. This enables overlapping subnets within an organization, but can result in duplication if the same network is scanned in different sites within the same organization.
Since scan analysis occurs at the site level, the boundaries you define for a site set the default scope for scans for that site. ## Explorer {#discovering-explorer} Select the ((Explorer)) to run the scan from, chosen from the set of registered Explorers for the site. The Explorer you choose must be able to directly communicate with the networks and addresses you define for the discovery scope. The chosen Explorer should ideally be able to reach all addresses in the scope directly, without a firewall in the way. ((Stateful firewalls)) and ((VPN gateways)) may interfere with the discovery process. ## Hosted External Explorer {#discovering-hosted-external-explorer} runZero Platform users can perform scans of public IP space using runZero-hosted Explorers. When creating a scan, choose a ((Hosted External Explorer)) in the 'Run task with' dropdown. When using this option, the discovery scope must use public IP addresses or ranges, or resolve to public IP space. ## Discovery scope The discovery ((scope)) defines the IP addresses that will be scanned. The scope uses the site settings when specified as they keyword "defaults", but may be changed on a per-scan basis as well. The scope should include at least one IP address or hostname. IPv4 ((address ranges)) can be specified in most standard formats: * `10.0.0.1` * `10.0.0.0/24` * `10.0.0.0/255.255.255.0` * `10.0.0.1-10.0.0.255` IPv6 addresses can be specified individually, but IPv6 ranges are not supported. ((Hostnames)) specified in the scope will be resolved at runtime by the assigned Explorer. If the hostname returns multiple IP addresses, all addresses in the response will be scanned. Hostnames can also have masks applied, indicating that the mask should expand to each resolved address of the hostname. For example, if `example.com` resolves to both `1.2.3.4` and `5.6.7.8`, the input of `example.com/24` would become `1.2.3.0/24` and `5.6.7.0/24`. IPv6 addresses returned from hostname resolution will be scanned if the Explorer has a valid IPv6 address and route to the target.
Note
runZero load balances the scan across as many subnets as possible, in a quasi-random order.
### Discovery keywords The following keywords are supported for both scan scopes and exclusions. * **asn4**: The `asn4:` keyword can be used to specify IPv4 ranges associated with a given AS number. * **country4**: The `country4:` keyword can be used to specify IPv4 ranges associated with a given two-character country code. * **public** and **private**: The `public:` and `private:` keywords can be used to specify IPv4 and IPv6 addresses associated with assets in the current organization. The mode parameter can be set to `all`, `primary`, or `secondary` to indicate which IP addresses are used. The `public` keyword selects all non-reserved IP addresses associated with organization assets. The `private` keyword selects all RFC-1918 and private use IP addresses associated with organization assets. * **domain**: The `domain:` keyword is available to cloud-hosted users and uses the syntax `domain:` to automatically select publicly-known hostnames for a given domain name. ## Scan name You can assign a name to your Scan task to make it easier to keep track of. ## ((Scan speed)) Specify the maximum ((packet rate)) for the overall discovery process, in network packets per second. 500 is conservative, 3000 works for most LANs including WiFi, 10000 or more may be helpful for large sites with fast connectivity. The scan speed directly affects how long the scan will take to complete. An approximate formula is: > time in seconds = hosts × ports × attempts ÷ scan speed The number of hosts scanned is primarily determined by the discovery scope. The number of ports is around 500 by default, and three attempts are made to connect. The number of hosts and ports scanned can be affected by the advanced scan options, and speed can also be impacted by maximum host rate and group size; see the descriptions of the advanced scan options below. Note also that this formula doesn't take into account time taken to take screenshots, follow web server redirects, or process the scan data. ## ((Schedule|scheduled scans)) You can set a date and frequency for your scan task. Dates and times take into account your browser's advertised timezone. Scans scheduled to start in the past will be launched immediately and then repeated at the specified time based at the frequency selected. ## Scheduling ((grace period)) Specify the number of hours to wait for an available Explorer before giving up on this scan. A zero or negative value will result in the scan retrying indefinitely until an Explorer becomes available. ## Scan duration limit You can specify a number of hours to limit scan duration to; if scanning is still in progress after this time has elapsed, the scan will be canceled. This does not limit processing time. If you set this to 0, no limit is applied. ## Advanced scan options The Advanced tab can be used to display and modify additional scan settings, such as network exclusions, scan speed, the ((ports)) covered by the TCP scan, and which ((probes)) are enabled. The default settings should work for most organizations but may need to be tweaked for slow networks or unreliable links. ### Maximum host rate As well as setting an overall scan rate in packets per second, you can also control the maximum rate at which packets are sent to any single host IP address. This is useful when you have devices which are easily overloaded by network traffic. The default should be safe for most systems. ### Max group size When runZero scans your network, it spreads the scan load across many IP addresses at once. The ((max group size)) determines how many IP addresses can be actively scanned at once -- allowing for the fact that hosts may take some time to respond to probes. The max group size needs to be at least as large as the overall scan speed, or else it would limit the speed of the scan to below the set value. If you provide a value that's lower than the overall scan speed, it will be increased automatically at scan time. The max group size is mostly useful when dealing with stateful network devices that can only track a limited number of connections at once, as a way to restrict how many active TCP sessions will result from a runZero scan. ### Max TTL The IP standards define a maximum hop count for packets. In IPv4, this is called the ((Time To Live)) or TTL, while on IPv6 this is called the Hop Limit. Every device processing a packet must decrease the TTL or Hop Limit one. If this value reaches zero, the route receiving the packet must discard the packet. This setting can be used to set the maximum hop limit for scan traffic. ### ToS The IP standards define a ((Type of Service)) or ToS for packets. In IPv4, this is called the ((Type of Service)) or ToS, while on IPv6 this is called the Traffic Class or TC. The ToS or Traffic Class is used by switches and routers to prioritize network traffic. The lower bits of the IPv4 ToS are also used for congestion controller. This setting can be used to set the ToS or Traffic Class for scan traffic. Please note that the ToS/Traffic Class settings do not apply to all traffic sent by runZero, but instead are limited to the basic discovery probes. Some protocols, such as SNMP, and integrations, such as VMware, do not set the ToS/Traffic Class fields on their corresponding packets. If all scan traffic must be consistently tagged with the correct ToS or Traffic Class, this can be accomplished through settings on the managed switch port instead. ### TCP ports The **Included TCP ports** and **Excluded TCP ports** fields can be used to override the default scan ports. The string "defaults" will lookup the current default port list at scan time. The current port list is:

### Prescan modes for large IP spaces Sometimes, the scope of your IP space is unknown, subnet usage is unknown, and the total number of assets is unknown. These unknowns can make it challenging to optimize your discovery scans for efficiency and speed. And when your IP space is large, like a /16 space with a few thousand IPs in use, a full discovery scan can take more time to complete, since it looks at more than 500 TCP ports and 15 UDP ports on every address. In these types of cases, you may want to tune your scan settings to prefilter ranges and IP addresses before a full scan. runZero has two ((prescan modes)) that you can use to run a faster scan: ((subnet sampling)) and ((host ping)). #### Subnet sampling To speed up scans of large subnets you can use the **"Only scan subnets with active hosts"** advanced scan option. If this option is on, a prescan runs against the target space to identify the subnets with an active host. This mode leverages heuristics runZero has collected to identify addresses that are more likely to be responsive across subnets. This process allows runZero to quickly scan larger spaces by identifying the subnets that are in use, before starting full probes. All subnets that are identified as having active hosts are then fully scanned -- unless you enable host pings. There are two tweakable parameters for subnet sampling. The ((sample rate)) determines what percentage of addresses in each subnet are prescanned to determine if the subnet should be scanned. The ((subnet size)) determines how many IP addresses are in each subnet. By default, the subnet size is 256 addresses, corresponding to a /24 subnet, and 3% of the addresses in each subnet are prescanned. #### Host ping After you have some insights on the subnets that are in use, you may want to limit the full scan to only addresses that respond to the most common ping methods, such as ICMP and some TCP and UDP ports. If you choose the **"Limit scans to pingable hosts"** advanced scan option, only hosts that respond to a ping request will be fully scanned. The runZero Explorer uses multiple protocols for ping scans: - Conventional ((ICMP ping)), performed by sending an ICMP echo request and looking for an ICMP echo reply. - ((TCP ping)), performed by sending a TCP SYN packet to a series of common ports and seeing whether the host responds with RST or TCP SYN/ACK. - ((UDP ping)), performed by sending a packet to port 65535 and checking for an ICMP response of port unreachable. The set of ports used for TCP and UDP ping can be adjusted in the LAYER2 section of the Probes and SNMP tab when setting up a scan task. Note that it is relatively common for enterprise firewalls to be set up to block ping, or for hosts to be set up not to respond to ping requests. Limiting scans to pingable hosts can therefore result in assets being missed entirely, even if their IP addresses are probed. If your goal is to speed up scan times, subnet sampling is usually the better option. It's possible to use both subnet sampling and limiting scans to pingable hosts at the same time, but this is not recommended except as a last resort for reducing scan times. --- docs/running-initial-scans.md --- title: "Initial network scans" --- ## Background {#firstscanbackground} Once you have an Explorer installed, you can start using it for network discovery. While our goal is to configure scheduled scans that we set and forget, we need to go about our first scans in a more structured manner. The goals of our ((first scans)) are to: - Verify the Explorer is setup properly and has everything installed - Validate Explorer connectivity to varying parts of the network - Determine how long scans will take at varying sizes to help with future scheduling ## Your first few scans To get started, you will want to scan a few smaller ranges to make sure everything is working as expected. Start with a few /24 network blocks from each of the ((RFC 1918)) ranges to make sure everything looks good. For setting up the first scan: 1. Navigate to **Sites > New Site > Create** a new temporary site within the Organization 2. Navigate to **Tasks > Scan > Standard Scan** to create a scan task 3. Chose the new site you created in step 1 4. Include a range of the RFC1918 IP addresses in the Discovery Scope, plus a small network or two that you know is in use. A suggested value for the RFC1918 range includes: ``` 10.0.0.0/24,10.0.255.0/24,10.64.0.0/24,10.64.255.0/24,10.128.0.0/24,10.128.255.0/24, 10.192.0.0/24,10.192.255.0/24,10.255.0.0/24,10.255.255.0/24,192.168.0.0/24,192.168.64.0/24, 192.168.128.0/24,192.168.192.0/24,192.168.255.0/24,172.16.0.0/24,172.23.0.0/24,172.31.0.0/24, ``` 5. On the Advanced tab, enable the _Subnet sampling_ option 6. Click on Initialize Scan After these scans are complete, you will want to check for these things: - Check the `ipv4.traceroute` value for assets in each RFC1918 range to verify you aren't sending traffic to an edge router or firewall. - Unused private IPs should have routes stubbed out to prevent traffic from being sent to the default gateway which can create a loop. You can also verify this with traceroutes from the Explorer. - If your scan results have a large series of somewhat sequential IPs that have only ICMP or a very small number of similar ports open on them, that's probably a proxy or firewall. Check out those IPs to see if any are real. To find assets with only ICMP enabled use the inventory query `alive:t AND service_count:=1 AND service_count_icmp:=1` - You can add an allow rule for the Explorer IP to properly scan devices on the other side - Another option is to add a second Explorer on the other side of the proxy or firewall - If you receive reports or alerts about service outages, check for session aware devices such as routers, firewalls, and proxies that are having issues handling the session load. If you run into this, there are multiple ways to approach solving the issue. - The simplest solution is to set up another Explorer on the other side of the device and run scans separately - Another option is to segment your scans on the existing Explorer, and run smaller, separate scan tasks for the network ranges on the other side of the device with lower packet per second and _max group_ sizes to minimize the number of IPs that will be scanned at once - Check how long each scan took to get an idea for how long larger scans would take - Verify you see screenshots on ports that accept HTTP/HTTPS requests - If you don't see any, you likely need to install Chrome on the machine - Check for MAC addresses - If you aren't seeing them you should configure SNMP - If SNMP is configured, you should verify community strings and check for unmanaged switches
Note
Once you have verified that your first scan ran successfully, you can delete the temporary site and set up a real scan.
## Full RFC 1918 scans Once you have completed initial test scans, it's time to expand scanning to cover all subnets with live assets. One method of discovering all subnets with live assets is to run full RFC 1918 scans. runZero offers a **Full RFC 1918 discovery** scan option that will discover assets across the following private address ranges as a single task. - 10.0.0.0/8 or 10.0.0.0-10.255.255.255 - 172.16.0.0/12 or 172.16.0.0-172.31.255.255 - 192.168.0.0/16 or 192.168.0.0-192.168.255.255
The Full RFC 1918 discovery scan option is only recommended for small networks with limited complexity and should only be leveraged in a single site configuration.
Discovering the entire RFC 1918 private address space in a single scan can takes days, if not weeks, to complete in a large complex network. runZero recommends reviewing the [Achieving RFC 1918 coverage](https://help.runzero.com/docs/playbooks/achieving-rfc1918-coverage/) playbook for more information on scanning the entire RFC 1918 private address space. Once you've completed scans of your private address space, review [Identifying gaps in scanning](identify-gaps-in-scanning.md) to learn more about some of our built-in reports that we offer to help you get a better understanding of your network. --- docs/identify-gaps-in-scanning.md --- title: "Identifying gaps in scanning" --- ## Background {#gapsbackground} After you have run a full network discovery scan, you can start to better understand your coverage and begin to optimize. By the end of this guide, you will understand how to use the out of the box reports in runZero to understand your gaps in network coverage. ### ((RFC 1918)) coverage {#identifying-gaps-rfc1918} The first report to look at is the **RFC 1918 coverage** report. This report shows you which internal IPv4 subnets have been scanned, which likely contain assets, and which are still unknowns. The scan coverage maps show all the addresses scanned within the `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16` ranges. See the legend to understand what percentage of each address space has been scanned. Clicking into any of the scanned subnets gives you access to the subnet grid for deeper asset analysis. **Identify scanned and un-scanned areas with the coverage map:** On the flip side, red outlines indicate that there are un-scanned addresses runZero has indirect knowledge of that haven't been scanned directly. For example, this can happen when runZero finds a secondary IP address on a multi-homed device within a scanned subnet. The red boxes highlight the subnets most likely to be in use, but un-scanned. **Scan missing subnets:** From the coverage report, you can launch a scan for any missing subnets in a given RFC1918 block – look for the binocular icon. **Scan missed subnets:** The missing subnets will be shown in the scan scope and the subnet ping will be enabled by default. You can tune the scan configuration as needed for your environment. ### ((Subnet utilization|subnet utilization)) {#identifying-gaps-subnet-utilization} The **Subnet utilization** report can provide similar visibility into your network to the RFC 1918 coverage report, but with emphasis on the subnets that contain live assets. This report will enumerate each of the subnets defined in your site definitions, and provide a count of live assets for that site and subnet, along with a utilization percentage. If there are live assets that are outside any site subnet, they will be aggregated into an inferred subnet based on the network mask size you select. From this report, you can pivot to the asset inventory for a given subnet or initiate a new scan of a subnet. Another benefit of this report is that you can export the results as a CSV. This can be helpful for more complex data analysis and for scheduling recurring scans. ### ((Switch topology|switch topology)) {#identifying-gaps-switch-topology} View layer-2 link information extracted from SNMP-enabled switches. This report can be used to find unmapped assets and investigate why they aren't showing up in your scans. **Configuration for this report:** The Switch Topology report uses data enumerated via SNMP to map switch ports to assets. In environments where SNMP v1 or v2 with default public or private communities are in use, this enumeration happens automatically. Non-default communities for SNMP v1/v2/v3 can also be provided in the scan configuration. Clicking on a node in this report will expand it to show its connections. **Finding unmapped MACs:** This topology view is helpful when trying to understand how a given asset or switch is connected, but also provides a critical data point related to risk; the number of unmapped assets. An unmapped asset is a MAC address connected to a switch, but not found in an ARP cache or through any of the other techniques runZero uses for remote MAC address discovery. **Re-scan to properly map MAC addresses:** For environments where a runZero agent is connected to each network segment, unmapped MACs may highlight VLANs or network segments that are missing from the scan scope. In environments where runZero is scanning assets multiple hops away, the unmapped asset count can provide an estimate of how well the remote segment is being identified. ### ((Unmapped MACs|unmapped MACs)) {#identifying-gaps-unmapped-macs} If you prefer a condensed view to see all unmapped macs, you can also use the Unmapped MACs report. This report shows all the unmapped MACs in your organization, organized by switch, and again by port. This data can be used similarly to the unmapped MACs data from the Switch Topology report. --- docs/managing-scan-templates.md --- title: "Managing scan templates" --- A ((scan template)) is a predefined set of scan options and settings. If you have a scan configuration you use often, you can create a scan template to save those settings. The next time you create a scan, you can choose a template instead of manually configuring your settings. Each update you make to the scan template is automatically applied to new and recurring scans based on the template, as well as any queued scans which were set up using the template but have not started yet. With scan templates, you can save time and reduce the likelihood of misconfiguring a scan. When you create a scan based on a scan template, you will not be able to edit the fields set by the template. However, you can configure the site, scan name, discovery scope, Explorer, and scan schedule, since these are not defined in the template. Each time a scan runs using values from a template, the scan task is saved with a copy of the parameters. This means the task will list the values used for the scan, even if the template is modified after the scan completes. ## Creating a scan template Scan templates can be created in a few ways in runZero: - By going to **Tasks > Task library** - From an existing scan task - Based on an existing scan template ### Creating a scan template from scratch 1. Go to **Tasks > Task library** to view the [task library](https://console.runzero.com/tasks/library). 2. From the **Task library**, click **Add template**. 3. When the scan configuration form appears, enter a name for the template. Use this name to search and assign the template to a new scan. 4. [Configure the scan](discovering-assets.md) as you normally would. The following tabs are available for you to access and configure settings: * **Standard** - Provide a name, description, and scan rate for the template. * **Advanced** - Configure excluded hosts, included ports, tags, host rates, group size, UDP probe max attempts, max TTL for all scan probe packets, ToS, screenshots, and subnet sampling. * **Probes and SNMP** - Enable SNMP and additional probes, and provide credentials. When you enable the SNMP probe, the scan will identify devices that are using the SNMP protocol, using the port and credentials provided to find anything with SNMP enabled. * **Credentials** - Enable any preconfigured [Scanning with credentials](scanning-credentials.md) you want to use for the scan. The scan uses the credentials if the defined CIDR scope matches the specific scan target. 5. Save the template. To use this template, go to the _Templates_ tab when you [configure a scan](https://console.runzero.com/scan/) or [create a Template scan](https://console.runzero.com/tasks/templatesNewScan) from the scan menu on the [inventory](https://console.runzero.com/inventory) or [tasks](https://console.runzero.com/tasks) pages. ### Creating a scan template from a scan task 1. Go to **Tasks** to open the [Tasks overview page](https://console.runzero.com/tasks/). 2. Find the scan task you want to use as the basis for your scan template and click the name to view the task details. 3. From the task details, click the **Copy** dropdown menu and choose **Copy for new template**. 4. When the scan configuration form appears, enter a name for the template. Use this name to search and assign the template to a new scan. 5. [Configure the scan](discovering-assets.md) as you normally would. The following tabs are available for you to access and configure settings: * **Standard** - Provide a name, description, and scan rate for the template. * **Advanced** - Configure excluded hosts, included ports, tags, host rates, group size, UDP probe max attempts, max TTL for all scan probe packets, ToS, screenshots, and subnet sampling. * **Probes and SNMP** - Enable SNMP and additional probes, and provide credentials. When you enable the SNMP probe, the scan will identify devices that are using the SNMP protocol, using the port and credentials provided to find anything with SNMP enabled. * **Credentials** - Enable any preconfigured [Scanning with credentials](scanning-credentials.md) you want to use for the scan. The scan uses the credentials if the defined CIDR scope matches the specific scan target. 6. Save the template. To use this template, go to the _Templates_ tab when you [configure a scan](https://console.runzero.com/scan/) or [create a Template scan](https://console.runzero.com/tasks/templatesNewScan) from the scan menu on the [inventory](https://console.runzero.com/inventory) or [tasks](https://console.runzero.com/tasks) pages. ### Creating a scan template based on a template 1. Go to the **Tasks > Task library** to view the [task library](https://console.runzero.com/tasks/library). 2. From the **Task library**, find the template you want to use as the basis for a new template and click the name to open it. 3. From the scan template configuration page, click **Copy**. runZero will duplicate and create a new scan template. 3. When the scan configuration form appears, enter a name for the template. Use this name to search and assign the template to a new scan. 4. [Configure the scan](discovering-assets.md) as you normally would. The following tabs are available for you to access and configure settings: * **Standard** - Provide a name, description, and scan rate for the template. * **Advanced** - Configure excluded hosts, included ports, tags, host rates, group size, UDP probe max attempts, max TTL for all scan probe packets, ToS, screenshots, and subnet sampling. * **Probes and SNMP** - Enable SNMP and additional probes, and provide credentials. When you enable the SNMP probe, the scan will identify devices that are using the SNMP protocol, using the port and credentials provided to find anything with SNMP enabled. * **Credentials** - Enable any preconfigured [Scanning with credentials](scanning-credentials.md) you want to use for the scan. The scan uses the credentials if the defined CIDR scope matches the specific scan target. 5. Save the template. To use this template, go to the _Templates_ tab when you [configure a scan](https://console.runzero.com/scan/) or [create a Template scan](https://console.runzero.com/tasks/templatesNewScan) from the scan menu on the [inventory](https://console.runzero.com/inventory) or [tasks](https://console.runzero.com/tasks) pages. ## Applying a scan template to a scan Instead of manually configuring a scan, you can choose to use a template instead. You can find all templates available for a scan on the **Templates** tab in your scan configuration. You can also go to the **Task library** page and choose to **Create a scan based on this template** from the template's actions. ## Editing a scan template All updates to a scan template affect every scan that uses it. After you make a change to a template, the next scan will automatically update to use the new settings. Any scan queued to run will use the new settings. ### Editing a scan that uses a scan template Any changes to a template will affect all scans that use them. If a scan uses a template, you will need to edit the template in order modify the scan settings. Otherwise, you will need to delete the scan and create a new scan configuration with your modifications. When you create a scan based on a scan template, you will not be able to edit the fields set by the template. However, you can configure the standard fields, such as the site, scan name, discovery scope, Explorer, and scan schedule, since these are not defined in the template. ## Deleting a scan template Deleting a template will remove it permanently from runZero. All configurations will no longer be accessible. To delete a scan template, go to [the Task library](https://console.runzero.com/tasks/library), find the template you want to delete, and click **Delete**. A dialog will prompt you to confirm that you want to delete the template, and the action will be irreversible. --- docs/scanning-credentials.md --- title: "Scanning with credentials" aliases: ["/docs/credentials"] --- The ((Credentials)) page provides a single place to store any secure credentials needed by runZero, including: - SNMPv3 credentials - Access secrets for cloud services like AWS and Azure - API keys for services such as Censys and Miradore Credentials are stored in encrypted form in the runZero database. Credentials, such as SNMP passwords, are used by runZero Explorers and are transmitted to them in encrypted form. For security reasons, the secret part of any credential cannot be viewed once entered. When adding a credential, you can choose to make it a ((global credential)) that can be used for all organizations or to allow access only by specific organizations. The **Allow all** or **Disallow all** buttons let you quickly apply the same setting across all organizations. Individual organizations can also be toggled to allow or disallow access. Most credential fields can be edited after the credential is saved. Some fields, like URLs, cannot be edited after saving for security reasons. Sensitive fields, such as passwords or access keys, will be hidden but can be overwritten. ## Credential settings The specific fields and options for a credential depend on the type of credential. VMware and SNMP credentials, which are used by the runZero Explorer, allow a CIDR allow list to be specified. This can be used to limit which scanned IP addresses the credential will be used with. This feature allows you to avoid sending SNMP or VMware credentials to all scanned hosts on the network, and instead limit them to specific IP addresses or ranges. ## Credential verification Credentials can be verified when created or edited to ensure they can successfully authenticate. Choose **Verify & save** when creating or editing a credential to run the verification before saving. If verification fails, it will display an error message and then give you the option to **Save anyway**. **Save anyway** will save the most recent verification status. ## Credential management Users must have administrator-level permissions to manage credentials. Users with **Administrator** as their [default role](managing-your-team.md) can fully manage all credentials. Users with [per-organization permissions](organizations.md) do not have access to global credentials, and are only able to manage credentials in organizations where they have administrator permissions. A shared credential cannot be deleted by an organization administrator. --- docs/scanning-snmp.md --- title: "Scanning with SNMP" aliases: ["/docs/snmp"] --- ((SNMP)) is an open standard network protocol for collecting information about devices on a network. There are three main versions of the protocol. ## SNMP versions 1 and 2 SNMP version 1 was designed in the 1980s as an interim protocol, intended to be replaced by ISO CMIP. It was built to be used across any network common at the time, not just TCP/IP networks, so security was left up to the host network. The protocol defined a community string for arbitrary organization of groups of assets, but didn't specify how access should be granted. SNMP version 2 attempted to introduce a security model based on "parties," but it wasn't widely adopted so a revised standard was issued as SNMP v2c. SNMP v2c removed party-based security and went back to just using ((community strings)). The previous SNMP v2 specification is considered obsolete. Unfortunately, both SNMP v1 and SNMP v2 send community strings in plain text across the network. There's no encryption of SNMP v1 or v2 data packets, and because the protocol is based on UDP there's no way to simply add TLS to make a secure connection. ## SNMP version 3 SNMP v3 fixes the security problems of SNMP v2 by supporting both password-based authentication and encryption (referred to as privacy protection) as part of the standard. Unfortunately there are multiple algorithms supported for both the encryption and the password authentication, and you have to know which ones your network devices use. Unlike SSH for example, the protocol doesn't include any kind of negotiation of encryption methods. SNMP v3 devices can operate in three different modes: - ((noAuthNoPriv)), meaning no authentication is required and there's no privacy protection (no encryption), - ((authNoPriv)), meaning authentication _is_ required but there's still no privacy protection, and - ((authPriv)), meaning both authentication and privacy protection are required. ## runZero's SNMP support runZero supports SNMP v1, SNMP v2 (the common `v2c` variant), and SNMP v3. Scans can be performed using only v1/v2, only v3, or both. SNMP scanning is on by default. You can turn it off or customize it using the SNMP tab when setting up a scan or a scan template. ### SNMP v1 & v2 scanning There are two ways to set up community strings for SNMP v1/v2 scanning. The first is to enter them as a comma-separated list on the SNMP tab. By default, runZero supplies the community strings `public` and `private`, as these are common defaults on network-enabled hardware such as printers and NAS servers. If you remove those defaults, runZero will not probe with them. The second way to set up community strings is to enter them using the [credentials feature](scanning-credentials.md) as the credential type _SNMP v2 Communities_. While communities technically shouldn't be used as credentials because they're sent in plain text across the network, in practice many networks use them that way. By entering your community strings as ((credentials|SNMP credentials)), you can use the ((CIDR allow list)) feature to control which parts of the network the community strings will be sent to, reducing the risk of their being captured by rogue devices. If you remove all community strings from the SNMP tab and do not set up any ((SNMP v2 Communities)) as credentials, no SNMP v1/v2 scanning will be performed. ### SNMP v3 scanning Most devices which provide potentially sensitive information such as serial numbers and software versions will only do so in response to an _authenticated_ SNMP v3 query. To perform ((authenticated SNMP v3)) scanning, you will need to set up an _SNMP v3 Credential_ record in runZero's credentials feature. The ((authentication protocol)) determines the hashing algorithm used to process the ((authentication passphrase)) -- that is, how the runZero Explorer logs in to the remote device. The most common default algorithm that devices use for authentication is `sha` (HMAC-SHA-96), which is required to be supported by the SNMP v3 standards. Newer devices may support more secure variants such as SHA-256, and runZero supports up to SHA-512. HMAC-MD5-96 is also supported, as per the standards, but is best not used on your network because the MD5 algorithm is known to be insecure. The ((privacy protocol)) determines how the data sent to and from the remote device is encrypted to prevent eavesdropping. The ((privacy passphrase)) is used as seed data to initialize the encryption. The most common privacy algorithm, required by the original SNMP v3 standards, is CBC-DES-128. It's selected as `des` in the runZero user interface. Later RFCs added AES-128, represented as `aes`. Again, runZero supports more secure variants that may be used by newer devices, such as AES256. As [mentioned above](#snmp-version-3), devices may require only authentication, both authentication and privacy, or neither. For some devices there is only space for a single passphrase in the device configuration. This usually means that the same passphrase is used for both the privacy passphrase and the authentication passphrase, if the device is running in authPriv mode. As with SNMP v2 community strings, you can set a CIDR allow list to determine which IP addresses SNMP v3 credentials will be sent to. This is particularly recommended if your network is not set up to require privacy passphrases. In addition to credentialed scanning, runZero will gather information from the pre-authentication handshake of SNMP v3. To perform SNMP v3 scanning across Cisco switches, modify the ACLs to include the following rule: - Newer IOS versions: `snmp-server group YourGroupName v3 auth context vlan- match prefix` - Older IOS versions: `snmp-server group YourGroupName v3 auth context vlan-1` (repeated for every VLAN) ### Choosing which versions of SNMP are scanned To disable SNMP v1/v2 and only scan with SNMP v3, remove the community strings from the SNMP tab when setting up a scan or template and ensure that any SNMP v2 community strings stored as credentials are disabled on the Credentials tab. To disable authenticated SNMP v3 scanning and only scan with SNMP v1/v2, ensure that any SNMP v3 credentials are disabled on the Credentials tab and make sure you have community strings specified, either on the SNMP tab or a credential. To disable all SNMP scanning, including uncredentialed SNMP v3, switch off the toggle switch on the SNMP tab labeled _Use the SNMP protocol for discovery_. ### How scans are performed runZero will probe devices using all configured SNMP versions and all community strings. This is because devices often respond with different levels of data for SNMP v3 versus SNMP v2, and may respond with different information depending on community string. SNMP is based on UDP, and UDP doesn't guarantee the order of data packets, so it's impossible to guarantee in what order community strings will be received by remote devices. SNMP v3 authentication errors are not treated as scan failures. This is because it's common to have multiple sets of SNMP v3 credentials used on different parts of a network, as well as misconfigured devices with incorrect passphrases. ## Checking SNMP v3 credentials and SNMP v1/v2 authentication If you are not getting SNMP data in your assets and think that you should be, a common cause is network firewalls, which often block SNMP traffic entirely. If possible, deploy an Explorer on the other side of the firewall, on the network segment you want to scan with SNMP. The second most common reason for not getting the expected SNMP data in assets is incorrect SNMP v3 credentials. - If SNMP v3 authentication was attempted, you will see an _SNMP engine ID_ recorded in the asset as `snmp.engineID.raw`. The engine ID is usually a long string of hex digits and is used to calculate access keys. - If SNMP v3 authentication failed, you will see an error reported in the attribute `snmp.failedAuth`. If the error is a request timeout, that likely indicates that authentication succeeded but the encrypted data channel could not be set up, which means you may have the wrong privacy password or privacy algorithm. - If SNMP authentication was attempted successfully (v1/v2 or v3), you will see an `snmp.credentials` attribute with the UUID of any credentials record that succeeded. - If SNMP v1/v2 authentication via community string succeeded, you will see `snmp.secretCommunities` or `snmp.defaultCommunities` attributes, depending on the type of community string. - If SNMP v1/v2 authentication succeeded using community strings entered directly into the task request rather than credentials records, the `snmp.secretCommunities` and/or `snmp.defaultCommunities` attributes will still be present, but `snmp.credentials` will be a zero UUID. ### Debugging credential issues It can be frustrating to ((debug SNMP v3)) credential problems by trial and error using multiple scan attempts. Instead, you can use the `snmpwalk` utility. It's part of the [net-snmp](http://www.net-snmp.org/) open source project, packaged for most Linux distributions and available for macOS via Homebrew. There are unofficial builds for Windows, or you can install it in the Windows Subsystem for Linux (WSL). The `snmpwalk` utility will connect to an IP address and dump all of the information it can retrieve. Here's an example of how to use it to connect in `authPriv` mode with both authentication and privacy passphrases: ``` snmpwalk -v3 -l authPriv -a SHA -A "authentication passphrase" -x AES -X "privacy passphrase" -u username 10.0.1.25 ``` (Text above has been line-wrapped, but it's one long command.) The parameters are: - `-v3`: switch to SNMP v3 mode. - `-l authPriv`: run in [authPriv](#snmp-version-3) mode, with both authentication and privacy required. - `-a SHA`: authentication algorithm is SHA (SHA-128). - `-A`: specify the authentication passphrase as the next argument. - `-x AES`: privacy (encryption) algorithm is AES (AES-128). - `-X`: specify the privacy passphrase as the next argument. - `-u username`: specify the login username. - `10.0.1.25`: the IP address to probe. If you have the right passphrases and algorithms, you'll get data back, probably a lot of it. If not, you'll get an error message which may help identify the cause. To check SNMP v2 community strings, you can use a command like this: ``` snmpwalk -v2c -c commstring 10.0.1.25 ``` The `-v2c` argument chooses SNMP v2 (SNMP v2c) mode, and the `-c` argument specifies the community string. If you have the wrong community string, `snmpwalk` will run for a while and then print a timeout error. ## Reviewing discovered SNMP services When SNMP services are found during a scan, their protocol versions are tracked at the asset level where you will see `snmp` in addition to `snmp1`, `snmp2`, and `snmp3` depending on which version responded. This makes for performant queries via the [asset inventory](https://console.runzero.com/inventory), such as when querying for `protocol:snmp2`. Addtionally, SNMP services track how they authenticated and which protocols they used. If a commonly used value for a SNMP v2 community was used (such as `public`, `private`, some vendor defaults, and common values like `password`, `cisco`, and `community`), these will be listed in cleartext in the service details under `snmp.defaultCommunities` and asset details under `snmp.v2DefaultCommunities` with the list of communities that responded. If the SNMP v2 community is not a common value, this will be reported as `snmp.secretCommunities` with a value of `true` in the service details and in an attribute called `snmp.v2SecretCommunities` with a value of `true` in the asset details. If SNMP v3 is used, then `snmp.v3Usernames` will be populated at the asset level. Lastly, an asset attribute called `snmp.auth` is populated indicating whether `v2DefaultCommunity`, `v2SecretCommunity`, or `v3Username` was successful to authenticate to the asset. ## Object Identifiers (OIDs) While some of these OIDs are used only for specific vendors, this is a complete list of all OIDs potentially used on a given asset. **System attributes** - `1.3.6.1.2.1.1.*.0` **IP addresses** - `.1.3.6.1.2.1.4.20.1.3.*` **MAC addresses** - `.1.3.6.1.2.1.2.2.1.6.*` **ARP caches** - `.1.3.6.1.2.1.4.35.1.4.*` - `.1.3.6.1.2.1.3.1.1.2.*` - `.1.3.6.1.2.1.4.22.1.2.*` **Routes** - `.1.3.6.1.2.1.4.24.7.1.7.*` **Port (CAM) tables** - `.1.3.6.1.2.1.17.7.1.2.2.1.2.*` - `.1.3.6.1.2.1.17.4.3.1.2.*` **VLANs** - `.1.3.6.1.2.1.17.7.1.4.3.1.1.*` - `.1.3.6.1.4.1.9.9.46.1.3.1.1.4.1.*` **Interface names** - `.1.3.6.1.2.1.17.1.4.1.2.*` - `.1.3.6.1.2.1.31.1.1.1.1.*` **Serial numbers** - `.1.3.6.1.2.1.47.1.1.1.1.11.*` **Device models** - `.1.3.6.1.2.1.47.1.1.1.1.13.*` **Hostnames** - `.1.3.6.1.4.1.9.2.1.3.*` **Model names from Juniper switches** - `.1.3.6.1.4.1.2636.3.1.2.0.*` **Serial numbers from A10 devices** - `.1.3.6.1.4.1.22610.2.4.1.6.2`
Note that for Cisco Catalyst & Nexus switches, the explorer requires per-VLAN access to the ARP/FDB tables using either community indexing (v2) or contexts (v3). runZero automatically enumerates the ARP cache and port table for each discovered VLAN. Without this access, you may not see the snmp.macs.ports and snmp.macs.vlans attributes discovered for a switch and the switch may not appear on the Switch Topology report.
Please note that Cisco Catalyst & Nexus switches require per-VLAN access to the ARP/FDB tables using either community indexing (v2) or contexts (v3). runZero automatically enumerates the ARP cache and port table for each discovered VLAN. runZero gathers information from SNMP v3 systems even when credentials are not available. This information includes the engineID as well as values from the following OIDs - `.1.3.6.1.6.3.15.1.1.1.0`: `usmStatsUnsupportedSecLevels` - `.1.3.6.1.6.3.15.1.1.2.0`: `usmStatsNotInTimeWindows` - `.1.3.6.1.6.3.15.1.1.3.0`: `usmStatsUnknownUserNames` - `.1.3.6.1.6.3.15.1.1.4.0`: `usmStatsUnknownEngineIDs` - `.1.3.6.1.6.3.15.1.1.5.0`: `usmStatsWrongDigests` - `.1.3.6.1.6.3.15.1.1.6.0`: `usmStatsDecryptionErrors` --- docs/using-custom-fingerprints.md --- title: "Using custom fingerprints" --- Customers running a ((self-hosted)) instance or using the standalone ((scanner)) have the ability to use custom-written fingerprints. This can be useful in adding new fingerprint coverage for very unique or custom assets and services, such as device prototypes or proprietary applications/services. Custom fingerprints can also be used to override existing, similar runZero fingerprints by using a same-or-higher certainty value.
Note
When using the runZero standalone scanner with custom fingerprints, you'll need to use the `RUNZERO_EXTERNAL_FINGERPRINTS` value as an environment variable when launching the scanner.
## Create new fingerprints {#custom-fingerprints-create} Custom fingerprints follow the structure and format of the [open-source Recog fingerprint database](https://github.com/rapid7/recog). You can author your own fingerprint XML entries in files of similar name and format to [those found in Recog](https://github.com/rapid7/recog/tree/main/xml). For cases where an asset or service matches both a built-in runZero fingerprint and a custom fingerprint of the same kind, preference will be given to the fingerprint with higher "certainty" value(s) (e.g. `hw.certainty`, `os.certainty`, `service.certainty`). In the event of a certainty "tie" (i.e. same certainty value(s)), the custom fingerprint will be given preference. ## Add new fingerprints to your self-hosted runZero instance To ensure the self-hosted instance of runZero can properly access your custom fingerprints, they will need to exist within the runZero installation directory ([/opt/runzero](docs/self-hosting.md#permissions) by default). The following steps will get your custom fingerprints setup for use by runZero: * Create a new directory within the runZero install directory (e.g. `mkdir /opt/runzero/myfingerprints`) * Update your `/etc/runzero/config` file with the new directory location (see below) * Copy your custom fingerprint XML files into the new directory (e.g. `cp *.xml /opt/runzero/myfingerprints`) The `/etc/runzero/config` file needs to be updated with the location of your custom fingerprints directory, which you can do by using your favorite editor to add the following line to the end of your config file (swapping `myfingerprints` with the name of the directory you added): ``` RUNZERO_EXTERNAL_FINGERPRINTS=myfingerprints ``` Note that you only need to do the directory creation and update of `/etc/runzero/config` file once. After that, you can add, remove, or modify your custom fingerprints in the directory as needed and then restart the runZero application to reload the current custom fingerprints. ## Restart the runZero service {#custom-fingerprints-restart} The runZero self-hosted instance will need to be [restarted](docs/self-hosting.md#restart-the-runzero-service) when custom fingerprints are added, removed, or updated. On restart, the runZero log file can be monitored to verify if the custom fingerprints were successfully applied or if an error occurred. On successful load of custom fingerprints, a log message like the following should be present: ``` @cee:{"level":"info","msg":"loaded (5) external fingerprints","time":"2022-09-12T19:51:49Z"} ``` If issues are encountered when loading or processing custom fingerprints, or if a 10 second timeout is reached, a warning message will be logged and the runZero application will continue running without any custom fingerprints. ## Verify your fingerprints {#custom-fingerprints-verify} Once your custom fingerprints have been added to your self-hosted runZero instance and the instance restarted, you can verify that the custom fingerprints are performing as-expected in one of the following ways: * Running a scan task to go scan a relevant asset/service, or * Importing an existing scan data file of the relevant asset/service Following completion of the scan task OR the import of scan data, depending on which method you chose, you can then navigate to a [specific asset](https://console.runzero.com/inventory) or [specific service](https://console.runzero.com/inventory/services) and verify that your custom fingerprints are acting as-expected. --- docs/traffic-sampling.md --- title: Passive sampling --- runZero Explorers can identify assets, services, and vulnerabilities by passively monitoring network traffic. ((Passive sampling)) can be an alternative data source when active scanning is prohibited and helpful at identifying unknown IP ranges. Passive sampling tasks are limited to using a single CPU core and will temporarily skip packets when this limit is reached. If an active scan is run on an Explorer with a passive sampling task, the passive task will be interrupted, and then restarted once the active scan completes. ## Configuring passive sampling Passive sampling can be configured from the Explorer details screen. Choose _Deploy_ from the left navigator and click on an Explorer. The network interfaces available for passive sampling will be shown on the left. Once enabled, the sampling task will process any available traffic received on these interfaces, including plain layer-2 frames from ((SPAN)) and ((TAP)) ports, encapsulated traffic using 802.1q (aka VLAN or QinQ), and layer-3 encapsuled traffic using GRE or VXLAN. While a full ((SPAN)) capture will provide the best results, any traffic, including broadcast, is useful for additional enrichment. Passive sampling tasks will automatically enabled ((promiscuous mode)) for the specified interfaces. Some virtual infrastructure, such as VMware ESXi, may require promiscuous mode to be enabled on the virtual switch before traffic is forwarded to the interface. The _Discovery scope_ specifies which IP ranges should be considered for asset, service, and vulnerability creation. Traffic that doesn't include a source or destination within an allowed range will be ignored. You can also specify _Excluded hosts_ if there are IP ranges you want to skip. The _Site_ option specifies where assets should be created and updated. If the same IPs exist in other sites, this can lead to duplicate asset records. You can set _Asset tags_ for systems identified through passive traffic sampling. This can be helpful for reviewing the new assets and setting up scans to obtain more information about them. --- docs/integrations-inbound.md --- title: "Inbound integrations" aliases: ["/docs/integrations/"] --- ## Enriching runZero results with data from other tools The runZero platform offers integrations with several sources of asset data, allowing users to enrich their asset inventory and identify assets and subnets that are not effectively managed or protected. By leveraging product APIs and export/import functionality, runZero can pull data from many IT and security tools to extend visibility across your organization's network. ## Supported integrations ### Cloud and virtualization * [Amazon Web Services](docs/aws.md) * [Google Cloud Platform](docs/google-cloud-platform.md) * [Microsoft Azure](docs/azure.md) * [Prisma](docs/prisma.md) * [VMware](docs/vmware.md) * [Wiz](docs/wiz.md) ### Endpoint protection * [CrowdStrike Falcon](docs/crowdstrike.md) * [Microsoft 365 Defender](docs/microsoft-365-defender.md) * [Microsoft Intune](docs/microsoft-intune.md) * [Miradore MDM](docs/miradore.md) * [SentinelOne](docs/sentinelone.md) * [Tanium API Gateway](docs/tanium.md) ### Endpoint management * [Microsoft Endpoint Configuration Manager (MECM)](docs/mecm.md) ### Asset and identity management * [Google Workspace](docs/google-workspace.md) * [Microsoft Active Directory](docs/microsoft-active-directory.md) * [Microsoft Entra ID](docs/microsoft-entra-id.md) (formerly Azure AD) ### Vulnerabilities and risk {#integrations-inbound-vm} * [Censys Search & Data](docs/censys.md) * [Dragos](docs/dragos.md) * [Qualys VMDR](docs/qualys.md) * [Rapid7](rapid7.md) * [InsightVM](rapid7-insightvm.md) * [Nexpose](rapid7-nexpose.md) * [Shodan](docs/shodan.md) * [Tenable](tenable.md) * [Tenable Vulnerability Management](tenable-vm.md) * [Tenable Nessus Professional](tenable-nessuspro.md) * [Tenable Security Center](tenable-sc.md) * [Tenable Nessus (file import)](tenable-nessus.md) ### Network management * [Cisco Meraki Dashboard](docs/meraki.md) ### Custom integrations If the solution you want to draw data from isn't available as a current runZero integration, Platform and Community users can leverage the [custom integrations](https://console.runzero.com/custom-integrations/) feature to add asset data from custom sources. Adding custom asset sources can be accomplished through the API or by leveraging the [runZero Python SDK](https://runzeroinc.github.io/runzero-sdk-py/). ## Scan probes or connector tasks {#integration-probe-connector} Most integrations can be run either as a ((scan probe)) or a ((connector task)). **Scan probes** run as part of a scan task. The scan task can be used to scan your environment and sync integrations at the same time. To run an integration as a scan probe: 1. Configure a scan task from the _Scan_ menu in your inventory or tasks page. 2. Activate the integration under the _Probes_ tab. 3. Activate the correct credential under the _Credentials_ tab. 4. Configure, activate, or deactivate other scan task configuration options as preferred. **Connector tasks** run independent of scan tasks in order to allow more finely tuned scheduling of integration syncs and asset scans. Connector tasks are run from the runZero cloud by default, but can be configured to run from an Explorer in your organization if preferred. To run an integration as a connector task: 1. Configure a connector task from the [Integrations page](https://console.runzero.com/integrations/) or the _Integrate_ menu in your inventory or tasks page. 2. Select an Explorer from the _Explorer_ menu (optional). 3. Configure, activate, or deactivate other connector task configuration options as preferred. ## Importing integration data Some integrations can be used by importing data from that platform into runZero. For example, `.nessus` files from [Tenable Nessus](docs/tenable-nessus.md) and `.xml` files from [Rapid7 Nexpose](docs/rapid7-nexpose.md) can both be ingested without requiring a connection to their APIs. ## Automatic asset merge {#integrations-merging} How runZero maps integration assets to assets: * For hosts that can be matched to an existing runZero asset, asset-level attributes will be updated, and integration-specific attributes will be added. * For hosts that cannot be matched with an existing runZero asset, a new asset will be created in the site specified when the integration task is set up. runZero is able to merge integration data into existing assets by the following, in priority order: 1. MAC address 2. IP address (3-day window) 3. Hostname Assets from integrations can also be manually merged into runZero assets using the _Merge_ button on the [Asset Inventory](https://console.runzero.com/inventory) page. ## Removing an integration data source {#integrations-removal} When an integration is removed as a data source, the associated attributes are removed from your runZero assets. Since some asset attribute fields are merged, it is possible that attributes populated by both runZero scans and the integration could be deleted. Rescanning the affected assets will resolve this issue. ## Excluding integration attributes Your account and organizations can be configured to prevent the collection of certain integration attributes; for example, personally identifiable information (PII) such as usernames or email addresses. Please note that some attributes are crucial to runZero's merging and fingerprinting methods, and excluding these attributes may lead to inaccuracies in your inventory. Excluded attributes can be configured in your [Account settings](https://console.runzero.com/account) under _Personally Identifiable Information (PII) collection_ to apply across all organizations, or configured within individual [Organization](https://console.runzero.com/organizations) settings to override the account-level settings. You can choose to use the default list of attributes or define your own. The attributes must be in the format `@source.resourceType.attributeName`. For example, `@crowdstrike.dev.firstLoginUser` excludes the attribute “firstLoginUser” from CrowdStrike devices. Only integrations that import PII support attribute exclusions, at this time those integrations are: * CrowdStrike * SentinelOne * Tanium * Google Workspace * Intune * Miradore Attribute exclusions are not supported for the Directory Users and Directory Groups inventories. The AzureAD, LDAP, and Google Workspace integrations import directory users and groups by default, but this can be disabled in the task configuration. ## Source names and IDs {#integration-sources} The table below maps the source name to the source ID for querying assets and vulnerabilities. --- docs/aws.md --- title: Amazon Web Services aliases: ["/docs/set-up-aws/"] --- runZero integrates with ((Amazon Web Services)) (((AWS))) to provide better visibility across your cloud environment. This integration imports data from each applicable API to add detailed information to your asset inventory: * [AWS EC2 API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html) * [AWS RDS API](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/ProgrammingGuide.html) * [AWS ELBv1 API](https://docs.aws.amazon.com/elasticloadbalancing/2012-06-01/APIReference/Welcome.html) * [AWS ELBv2 API](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/Welcome.html) * [AWS Lambda API](https://docs.aws.amazon.com/lambda/latest/dg/API_Reference.html) Syncing with AWS allows you to quickly identify the number of EC2 instances, elastic load balancers, and relational database services you have running, as well as their region, account, and more. This integration supports the import of all running EC2 instances, RDS instances, and active application, network, gateway, or classic load balancers. It can be configured to connect to a single AWS account or to all accounts in your organization and imports data across multiple regions. ## Getting started {#aws-getting-started} The following AWS resource types are supported: * EC2 instances * Elastic load balancers * RDS instances * Lambda instances To set up the AWS integration, you'll need to: 1. Configure AWS to allow API access through runZero. 2. Add the AWS credential to runZero, which includes the access key and secret key. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the AWS integration to sync your data with runZero. ## Requirements {#aws-requirements} Before you can set up the AWS integration: * Make sure you have access to the AWS console. * Make sure you are using [AWS Organizations](https://aws.amazon.com/organizations/) if you want to connect to multiple accounts. * When using [AWS Organizations](https://aws.amazon.com/organizations/) with compatible credentials, such as the [IAM Role Credential](#iam-role-credential), we enumerate member accounts to sync all data. ## Step 1: Create an AWS credential There are multiple options for creating an AWS credential: * [IAM Role Credential](#iam-role-credential) (recommended) - runZero authenticates to AWS using an IAM role that you create in your AWS account. No long-term access keys are needed. * Note that IAM Role credentials are not supported for self-hosted instances, GovCloud-based accounts, or Explorer tasks, and IAM Key credentials should be used in this case instead. * [IAM Role Credential - Manual Account Selection](#iam-multi-account-credential) (alternative) - runZero authenticates to AWS in the same manner as the IAM Role Credential, but using manually-specified account IDs rather than AWS Organization subaccounts. Recommended only for advanced use cases. * [IAM Key Credential](#iam-key-credential) (deprecated) - runZero authenticates to AWS using an IAM user and long-term access keys. ### Option A: IAM Role Credential {#iam-role-credential} When using an IAM role to provide runZero with authenticated access to AWS, you'll need to establish an **External ID**. An external ID is a unique ID provided by runZero for your IAM role. You'll use this external ID when configuring your IAM role to ensure that only your runZero account can access the role. To learn more about the use of external IDs in cross-account access, refer to [AWS' documentation on the confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). #### Step 1a.1: Create a runZero credential and external ID To generate an external ID, you'll need to create an AWS IAM Role credential in the runZero console: 1. In the runZero console, navigate to the [Credentials page](https://console.runzero.com/credentials/new) and click **Add Credential**. 2. Choose **AWS IAM Role** from the list of credential types. 3. Provide a name for the credential, like `AWS IAM Role`. 4. Enter the full ARN of the AWS IAM role you plan to create in the next step into the AWS IAM role ARN field. An IAM role ARN has the format `arn:aws:iam::123456789012:role/runzero-sync`, where `123456789012` is your AWS account ID and `runzero-sync` is the name of the role you will create. If you don't know your AWS account ID, that's ok. You can use `arn:aws:iam::XXXXXXXXXXXX:role/runzero-sync` as a placeholder and update it later. 5. Click **Save** to save the credential and generate an external ID. Note: Clicking Verify & Save will not work because you haven't created the IAM Role in AWS yet. You'll come back and test the credential in Step 1a.3. 6. Copy the external ID that was generated. You'll need it in the next step. #### Step 1a.2: Create AWS IAM role(s) You must create an IAM role using the directions below in every AWS account you want to sync with runZero. If you utilize AWS Organizations, you must reuse the same role name and external ID from your credential in each account. The preferred way to create an IAM Role is using CloudFormation StackSets: 1. Create a `runzero-cloudformation-stackset.json` file with the following content. Replace `` with the external ID generated using the runZero console. ```json "Resources": { "IamrunZeroAccessRole": { "Type": "AWS::IAM::Role", "Properties": { "RoleName": "runzero-sync", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::336004405641:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }] }, "ManagedPolicyArns": [ "arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess", "arn:aws:iam::aws:policy/AmazonRDSReadOnlyAccess", "arn:aws:iam::aws:policy/AWSLambda_ReadOnlyAccess", "arn:aws:iam::aws:policy/AWSOrganizationsReadOnlyAccess" ] } } } ``` 2. Go to **CloudFormation > StackSets** and click **Create StackSet**. 3. Select **Template is ready** and **Upload a template file**. Upload the template you downloaded earlier. 4. Enter a name for the StackSet, for example runZero-IAM-Role. Click next. 5. (Optional) Set tags. Click next. 6. Set deployment options. Click next. 7. Review and create the StackSet. 8. The StackSet will create an IAM Role of the format: `arn:aws:iam:::role/runzero-sync`. Copy the full ARN of the role you created. You'll need this in Step 1a.3. Alternatively, to create the IAM Role(s) manually: 1. Sign in to the AWS console. 2. Go to **Identity and Access Management (IAM) > Roles** to create a role that will provide access to runZero. 3. Click the **Create role** button 4. On the "Select trusted entity" step: 1. Select **AWS account** in the **Trusted entity type** panel 2. Select **Another AWS account** in the **An AWS account** panel 3. Enter `336004405641` for the account ID. This is the account runZero uses to access your AWS account. 4. Check the **Require external ID…** checkbox and enter the external ID that was generated in Step 1a.1. 5. Click the **Next** button to proceed to the next step. 5. On the "Add permissions" step, select the following AWS managed policies and click the **Next** button to proceed to the next step. These grant runZero read-only access to read inventory from your AWS account. - `AmazonEC2ReadOnlyAccess` to sync EC2 and ELB resources - `AmazonRDSReadOnlyAccess` to sync RDS instances - `AWSLambda_ReadOnlyAccess` to sync Lambda functions - `AWSOrganizationsReadOnlyAccess` to sync AWS Organization account information 6. On the "Name, review, and create" step, enter a relevant role name, such as `runzero-sync`, and description for the role. Once confirmed click the **Create role** button. 7. Copy the full ARN of the role you just created. It will have the format `arn:aws:iam:::role/`. You'll need this in Step 1a.3. Additional Notes: - Often, payer accounts are not able to be StackSet-configured by default. In these cases, the StackSet approach can configure all member accounts, and the payer account may need to be manually configured. - If you intend to sync with AWS regions that are not enabled by default, [change the region compatibility of the global STS endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html?icmpid=docs_iam_console#sts-regions-manage-tokens). To do this, in the AWS console navigate to IAM -> Account Settings -> Security Token Service (STS). Then change the Global Endpoint to be compatible with “All AWS Regions.” ### Step 1a.3: Update the runZero credential 1. Return to the runZero console, navigate to the [Credentials](https://console.runzero.com/credentials/) page and edit to the Credential you created in Step 1a.1. 2. Update the **AWS IAM role ARN** field with the full ARN of the role you created in Step 1a.2. 3. Use the **Verify & Save** button to save and test the credential. You're now ready to set up and activate the connection to bring in data from AWS. Continue to [Step 2](#aws-choose-configuration). ### Option B: IAM Role Credential - Manual Account Selection {#iam-multi-account-credential} This option should only be chosen when the default IAM Role Credential does not provide sufficient flexibility in targeting a subset of AWS accounts. Please consider this carefully, as there is additional operational overhead in using it. #### Step 1b.1: Create a runZero credential and external ID This step should look very similar to step 1a.1. To generate an external ID, you'll need to create an AWS IAM Role credential in the runZero console: 1. In the runZero console, navigate to the [Credentials page](https://console.runzero.com/credentials/new) and click **Add Credential**. 2. Choose **AWS IAM Role - Manual Account Selection** from the list of credential types. 3. Provide a name for the credential, like `AWS IAM Role - Manual`. 4. Enter the name of the role you are using for all accounts into the AWS IAM Role field. 5. Enter a newline-separated list of the account IDs you would like to import asset information from. An AWS account ID will be a 12-digit number, so an entry would look like `123456789012`. 6. Click **Save** to save the credential and generate an external ID. Note: Clicking Verify & Save will not work because you haven't created the IAM Role in AWS yet. You'll come back and test the credential in Step 1b.3. 7. Copy the external ID that was generated. You'll need it in the next step. #### Step 1b.2: Create AWS IAM role(s) Refer to step 1a.2, as this uses the same setup as that credential type. Note that the setup will need to be repeated for each account that you intend to import asset data from, as this credential type does not use AWS Organizations like the IAM Role Credential. ### Step 1b.3: Update the runZero credential 1. Return to the runZero console, navigate to the [Credentials](https://console.runzero.com/credentials/) page and edit to the Credential you created in Step 1b.1. 3. Use the **Verify & Save** button to save and test the credential. You're now ready to set up and activate the connection to bring in data from AWS. Continue to [Step 2](#aws-choose-configuration). ### Option C: IAM Key Credential {#iam-key-credential} If you created an IAM Role using Option 1 above, you may skip this step and proceed to [Step 2](#aws-choose-configuration) below. This section describes how to authenticate runZero to AWS using an IAM user and long-term access keys. Using long-term access keys is not recommended. We recommend using an IAM Role instead. #### Step 1c.1: Create an AWS IAM user 1. Sign in to the AWS console. If you are using AWS Organizations and intend to sync with multiple accounts, sign into the AWS Organizations management account, sometimes called the "payer" or "root" account. 2. Go to **Identity and Access Management (IAM) > Users** and select or create a user that will provide API access to runZero. 3. Click **Add permissions > Attach existing policies directly**. Search for and attach the following policies based on the services you would like to sync: - `AmazonEC2ReadOnlyAccess` to sync EC2 and ELB resources - `AmazonRDSReadOnlyAccess` to sync RDS instances - `AWSLambda_ReadOnlyAccess` to sync Lambda functions - `AWSOrganizationsReadOnlyAccess` to sync AWS Organization account information 4. Add an inline policy to allow assuming runZero roles in sub-accounts (only required if using AWS Organizations): ```json { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::*:role/" }] } ``` 5. From the user summary screen, open the **Security credentials** tab and click on **Create access key**. 6. Save the **Access key ID** and **Secret access key**. You'll need them in Step 1c.3. 7. If you intend to sync with AWS regions that are not enabled by default, [change the region compatibility of the global STS endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html?icmpid=docs_iam_console#sts-regions-manage-tokens) to be compatible with All AWS Regions. To do this, in the AWS console navigate to IAM -> Account Settings -> Security Token Service (STS). Then change the Global Endpoint to be compatible with "All AWS Regions." #### Step 1c.2: Add an IAM role to sub-accounts If you are using AWS Organizations and want runZero to sync with all accounts in your organization, you must create an IAM role in each sub-account that allows the IAM user you created in Step 1c.1 to assume the role. If you aren't using AWS Organizations, you may skip this step and proceed to Step 1c.3. In every AWS sub-account: 1. Go to **Identity and Access Management (IAM) > Roles** and click **Create role**. 2. Choose **Another AWS Account** for the type of trusted entity. 3. For Account ID, enter the ID for your organization's management account. 4. Click **Next: Permissions**. 5. Attach the `AmazonEC2ReadOnlyAccess` policy if you want to sync EC2 and ELB resources. 6. Attach the `AmazonRDSReadOnlyAccess` policy if you want to sync RDS instances. 7. Attach the `AWSLambda_ReadOnlyAccess` policy if you want to sync Lambda functions. 8. Click **Next: Tags** and add tags optionally. 9. Click **Next: Review** and provide a name for the role. (The role must be named the same for all accounts) 10. Click **Create role**. #### Step 1c.3: Add the AWS credential to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click **Add Credential**. 2. Provide a name for the credential, like `AWS IAM User`. 3. Choose **AWS Access & Secret** from the list of credential types. 4. Provide the following information: * **AWS access key** - Access key ID obtained from Step 1c.1. * **AWS secret access key** - Secret access key obtained Step 1c.1 * **AWS role** - Assumed role used to connect to other accounts in your organization. This is the role name you used in Step 1c.2. * Select the region(s) that you want to sync. 5. Save the credential. ## Step 2: Choose how to configure the AWS integration {#aws-choose-configuration} The AWS integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 3: Set up and activate the AWS integration to sync data After you add your AWS credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 3a: Configure the AWS integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new AWS-only assets are created. 1. Activate a [connection to AWS](https://console.runzero.com/ingest/aws). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. Enter a name for the task, like `AWS sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**: * Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. You can also choose to **Automatically create a new site per VPC** or **Automatically create a new site per account**, and runZero will take care of creating the sites for newly discovered assets or accounts. * Choose whether to **automatically delete stale AWS assets**. If you check this option, runZero will automatically delete AWS assets previously seen in AWS that were not found in the most recent sync. * Choose whether to include AWS assets that are not currently running. If you check this option, runZero will import AWS asset data for assets that are not in a running state. 6. Under **Service options**, select the services you would like to sync data from. You must choose at least one. 7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 3b: Configure the AWS integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the AWS toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the AWS toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 4: View AWS assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your AWS assets. These assets will have an AWS icon listed in the **Source** column. To filter by AWS assets, consider running the following queries: * [View all AWS assets](https://console.runzero.com/inventory?search=source%3Aaws): ``` source:aws ``` * [View all AWS EC2 instances](https://console.runzero.com/inventory?search=source%3Aaws%20AND%20has%3A%22%40aws.ec2.instanceID%22): ``` source:aws AND has:"@aws.ec2.instanceID" ``` * [View all AWS Elastic Load Balancers](https://console.runzero.com/inventory?search=source%3Aaws%20AND%20%28has%3A%22%40aws.elb.loadBalancerArn%22%20OR%20has%3A%22%40aws.elb.loadBalancerName%22%29): ``` source:aws AND (has:"@aws.elb.loadBalancerArn" OR has:"@aws.elb.loadBalancerName") ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by the AWS APIs. ## Troubleshooting {#aws-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Amazon Web Services integration unable to connect? 1. Are you getting any data from the AWS integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the AWS integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/enriching-assets-with-ec2-metadata.md --- title: Enriching scans with EC2 h2Styled: false --- As part of a discovery scan, runZero will automatically enrich scanned assets with data from the ((AWS)) ((EC2)) API when available. runZero assets will be updated with internal IP addresses, external IP addresses, hostnames, MAC addresses, and tags, along with other EC2-specific attributes, such as the account ID and instance type. No additional configuration is needed in runZero to get this data enrichment. However, you may need to [modify the permissions](#add-permissions-to-describe-instances) associated with the instance's ((IAM)) role. ## Find Explorers with EC2 enrichment capabilities To use the EC2 enrichment capabilities, the runZero Explorer must be running on an instance with permissions to describe your EC2 instance list. This can be configured through an IAM role associated with the instance as well as by configuring the AWS credentials for the root user account. To identify the Explorers with this capability, view your [registered Explorers](https://console.runzero.com/deploy/explorers). Any Explorer with the cloud icon indicates that it can enumerate EC2 instances. Scans run from these Explorers will merge any EC2 instance fields into the asset automatically for any in-scope targets matched against the instance list. ## Add permissions to describe instances To allow for EC2 instance data enrichment, you will need to add the EC2 [`ec2:DescribeInstances`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) permission for the instance role configured for your instance. Visit the [Amazon docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-ec2-console.html) to learn how to create and update policies. Basically, your policy will look like: ``` { "Version": "2012-10-17", "Statement": [{ "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "ec2:DescribeInstances", ], "Resource": "*" } ] } ``` From the IAM UI, go to **Roles > Permissions > Attach policies** and search for the EC2 service. From the actions, select `DescribeInstances`, which is located under List. You can also configure credentials on the instance by running [`aws configure`](https://docs.aws.amazon.com/cli/latest/reference/configure/index.html) as root, instead of using the IAM instance role. After you save your policy, you'll need to restart your Explorer. The easiest way to do this is to force an update from the Explorer menu. Keep in mind if your configuration uses one region, but the instance is located in another, it will use the instance's region instead for all API requests. ## Attributes runZero gets from the EC2 API When runZero determines that an IP address is also an EC2 instance, it will enrich the existing runZero data with EC2 metadata. runZero will be able to pull in more hostnames based on AWS asset tags, MAC addresses, internal and external IPs. Some attributes that runZero is able to get from the EC2 API metadata: - aws.accountID - aws.architecture - aws.availabilityZone - aws.hypervisor - aws.imageID - aws.instanceID - aws.instanceType - aws.ipv4 - aws.ipv6 - aws.keyName - aws.launchTimeTS - aws.macs - aws.privateDNS - aws.privateIP - aws.publicDNS - aws.publicIP - aws.region - aws.rootDeviceName - aws.rootDeviceType - aws.scanner.instanceID - aws.scanner.instanceType - aws.state - aws.subnetID - aws.tags - aws.tenancy - aws.virtualizationType - aws.vpcID Additionally, runZero will also report on other things that respond to the scan, but don't match an EC2 entry. You may see things like Amazon RDS, temporary ELBs, and Lambdas in your inventory, but you will only see EC2 metadata on EC2 assets. --- docs/censys.md --- title: Censys Search & Data --- runZero supports importing assets from the [Censys Search API](https://support.censys.io/hc/en-us/categories/4405770552724-Censys-Search) and the [Censys Internet Dataset](https://support.censys.io/hc/en-us/sections/4405799086740-Universal-Internet-Data-Set). * [Importing assets from the Censys Search API](#censys-search-api) * [Importing assets from the Censys Universal Internet Dataset](#censys-universal-internet-dataset) ## Censys Search API To get started with the ((Censys Search)) API, you will need to register for a [Censys Search account](https://censys.io/register). Once you have done so, you can find your API credentials in the [My Account](https://search.censys.io/account/api) section. In runZero, go to the Credentials page, and click [Add Credential](https://console.runzero.com/credentials/new). Select _Censys Search API Key_ as the credential type, and enter your API ID and API secret. You can now go to your [asset inventory](https://console.runzero.com/inventory), click the **Connect** button, and choose **Censys Search API**. Select the credential you just created from the Censys Search credential dropdown. ### Configuration {#censysconfig} There are two modes for connecting runZero to the Censys Search API. * **Custom Query** mode - runZero runs a Censys search query you specify, and then imports all of the results into runZero. The search query should be in [Censys Search Language](https://search.censys.io/search/language?resource=hosts). It is a good idea to test your query using the main [Censys Search 2.0](https://search.censys.io/) interface before running an import task. * **All Assets** mode - runZero assembles a list of public IP addresses from all of the assets in the selected site, and then uses the API to find Censys Search information for those addresses. The information found is imported into runZero and merged into the appropriate assets. As with a runZero scan, you'll need to select a site to contain the scan data. The usual task scheduling options are available. When you have finished editing the Censys Search configuration, click **Activate Connection**. ## Censys Universal Internet Dataset To get started with the ((Censys Universal Internet Dataset)) API, you will need a paid Censys Data account and the associated API credential. You can find your API credentials in the [My Account](https://search.censys.io/account/api) section. The dataset can be downloaded by following the instructions in the [Censys documentation](https://support.censys.io/hc/en-us/articles/360038762111-Downloading-Raw-Files). The Search API is used to get a list of files for a given date and those individual files should downloaded into a local directory backed by SSD or NVMe storage. ### Creating the database The raw files are in Apache Avro format and need to be converted into a database for efficient queries. To process Censys data files, you use the runZero CLI's `censys-db-convert` command. This command takes two parameters: - The path to a directory containing the `.avro` files from Censys - The path to write the computed database ``` $ nice runzero censys-db-convert /home/censys/avro /home/censys/db ``` The default configuration requires substantial computing resources: - At least 8 CPU cores, but 16 or more is better - At least 64GiB of RAM, but more is better - At least 3Tb of storage backed by SSD or NVMe (1Tb+2Tb or single volume) An AWS `m5.4xlarge` with a 3Tb GP2 SSD volume meets these requirements and can process a full dataset (single day) in about 13 hours. The resulting database is about twice the size of the source data (1.3TiB database from 640GiB of Avro). Using the database requires additional disk overhead and over provisioning the storage also improves throughput. ### Querying the database After the Avro files have been converted to a local database, the `censys-db` command can be used to import data into runZero. The CLI queries the local database, and writes a file in runZero scan format containing the appropriate host records. By default, the file has a name matching `censys-*.rumble.gz` and is written to the current directory. Alternatively you can specify an output filename with the `--output-raw` option, as if performing a runZero scan. The runZero scan file can be uploaded to the runZero console like any other scan file. If you have more IP addresses or CIDRs than will fit on a command line, you can use the `--input-targets` option to specify that the CLI should read them from a file. The file is expected to be ASCII text, and contain CIDRs or IP addresses separated by whitespace (which can include newlines). You can also use the CLI to process data, upload it, and then delete the scan data file if everything succeeded. For example: ``` % runzero censys-db /home/censys/db \ 12.216.190.0/24 --upload --api-key=YOUR_ORGANIZATION_API_KEY \ --upload-site="Primary site" ``` If you are using self-hosted runZero, you can use the `--api-url` option to specify your console's API endpoint. The `censys` command also supports the `--verbose` option, which will make it list host addresses as they are written to the output file. ### Creating a local Censys Search API server The computed database can also be used to serve a limited, local version of the Censys Search API using the runZero CLI's `censys-db-server` command. Due to the size of the database, the system `vm.max_map_count` may need to be increased to avoid a memory map error. The memory map count can be increased by adding the following line to `/etc/sysctl.conf`: ```plain vm.max_map_count=262144 ``` Once this line is added, reload the sysctl.conf with the following command: ```bash $ sudo sysctl -p /etc/sysctl.conf ``` After the `vm.max_map_count` has been updated, start the Censys DB Server with the following command: ```bash $ runzero censys-db-server /home/censys/db ``` This will start a local web service on port 55555 by default (changeable via `--port `) that responds to the `/api/v2/hosts/search` and `/api/v2/hosts/` endpoints. Once this server is running, it can be queried using the runZero Censys Search API connector, and through other HTTP clients, such as curl: ```bash $ curl http://127.0.0.1:55555/api/v2/hosts/search?q=ip%3A8.8.8.0/24 $ curl http://127.0.0.1:55555/api/v2/hosts/8.8.8.8 ``` ### Querying the raw Avro files without database processing runZero also supports direct queries of the unprocessed Avro files. These queries are slow and may take hours or days to complete depending on the query and local storage speed. To query the raw Avro files, you use the runZero CLI's `censys` command. It takes any number of arguments, which can be: - Names of Avro files, which must end in `.avro` - CIDRs or IP addresses to search for in the files The CLI reads the Avro files specified, and writes a file in runZero scan format containing the appropriate host records. By default, the file has a name matching `censys-*.rumble.gz` and is written to the current directory. Alternatively you can specify an output filename with the `--output-raw` option, as if performing a runZero scan. The runZero scan file can be uploaded to the runZero console like any other scan file. If you have more IP addresses or CIDRs than will fit on a command line, you can use the `--input-targets` option to specify that the CLI should read them from a file. The file is expected to be ASCII text, and contain CIDRs or IP addresses separated by whitespace (which can include newlines). You can also use the CLI to process data, upload it, and then delete the scan data file if everything succeeded. For example: ``` % runzero censys universal-internet-dataset-20210923-000000000000.avro \ 12.216.190.0/24 --upload --api-key=YOUR_ORGANIZATION_API_KEY \ --upload-site="Primary site" ``` If you are using self-hosted runZero, you can use the `--api-url` option to specify your console's API endpoint. The `censys` command also supports the `--verbose` option, which will make it list host addresses as they are written to the output file. ## Troubleshooting {#censys-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Censys Search integration unable to connect? 1. Are you getting any data from the Censys Search integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this integration documentation and follow the steps exactly. 3. If the Censys Search integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/meraki.md --- title: Cisco Meraki Dashboard --- runZero integrates with ((Cisco Meraki Dashboard)) by importing data from the [Cisco Meraki Dashboard API](https://documentation.meraki.com/General_Administration/Other_Topics/Cisco_Meraki_Dashboard_API). This integration allows you to sync data about your devices and network clients from Meraki to provide better visibility of your network. ## Getting started with Meraki {#meraki-getting-started} To set up an integration with Meraki, you'll need to: 1. Generate an API key for your Cisco Meraki Dashboard administrator account. 1. Configure the Meraki credential in runZero. 1. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 1. Activate the integration to pull your data into runZero. ## Requirements {#meraki-requirements} Before you can set up the Meraki integration: * Make sure you have administrator access to the Meraki Dashboard. ## Step 1: Generate an API key in Cisco Meraki Dashboard {#meraki-step1} 1. Sign in to Cisco Meraki Dashboard with an administrator account. 1. Check that access to the Cisco Meraki Dashboard API is enabled. This must be enabled for each organization you would like to sync. 1. Navigate to **Organization > Settings** and enable **API access** under **Dashboard API access**. 1. Navigate to **My profile** to generate an API key. The API key will inherit the same permissions as the account that created it. ## Step 2: Add the Meraki API key to runZero {#meraki-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. 1. Choose **Meraki API Key** from the list of credential types. 1. Provide a name for the credential, like `Meraki`. 1. Provide the following information: * **Meraki API URL** - The API Endpoint URL used to access the Cisco Meraki Dashboard API. * **Meraki API key** - The API key for the Cisco Meraki Dashboard administrator account. 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 1. Save the credential. You're now ready to set up and activate the connection to bring in data from Meraki. ## Step 3: Choose how to configure the Meraki integration {#meraki-step3} The Meraki integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#meraki-step4} After you add your Meraki credential, you'll need to sync your data from Meraki. ### Step 4a: Configure the Meraki integration as a connector task {#meraki-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Meraki-only assets are created. 1. Activate a connection to [Meraki](https://console.runzero.com/ingest/meraki). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Optionally provide a list of organization IDs or names to include in the import. The list must be comma-separated. We will only import data for the organizations specified. 1. Optionally provide a list of network IDs or names to include in the import. The list must be comma-separated. We will only import data for the networks specified. 1. Optionally provide a comma-separated list of VLANs to exclude from the import. We will not import devices associated with the specified VLANs. 1. If you want to exclude assets that are not associated with a VLAN, set the **Exclude clients with no VLAN** option to _Yes_. 1. Optionally provide a comma-separated list of SSIDs to exclude from the import. We will not import devices connected on the specified SSIDs. 1. Enter a name for the task, like `Meraki Sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. Enter a description for the task (optional). 1. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Meraki integration as a scan probe {#meraki-step4b} You can run the Meraki integration as a scan probe so that the runZero Explorer will pull your Meraki assets into the runZero Console. In a new or existing scan configuration: * Ensure that the `MERAKI` option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct `MERAKI` credential to _Yes_ in the _Credentials_ tab. ### Step 5: View Meraki assets {#meraki-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Meraki assets. These assets will have a Cisco icon listed in the **Source** column. To filter by Meraki assets, consider running the following queries: * [View all Meraki assets](https://console.runzero.com/inventory?search=source%3Ameraki): ``` source:Meraki ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from Meraki. --- docs/crowdstrike.md --- title: CrowdStrike Falcon aliases: ["/docs/set-up-crowdstrike/"] --- runZero integrates with ((CrowdStrike)) by importing data through the [CrowdStrike Falcon API](https://www.crowdstrike.com/blog/tech-center/get-access-falcon-apis/). This integration allows you to sync and enrich your asset inventory, as well as ingesting vulnerability data from Falcon Spotlight and software data from Falcon Discover. Adding your CrowdStrike data to runZero makes it easier to find things like endpoints that are missing an EDR agent. ## Getting started {#crowdstrike-getting-started} To set up the CrowdStrike integration, you'll need to: 1. Configure CrowdStrike to allow API access through runZero. 2. Add the CrowdStrike credentials, which will include the client ID and client secret, and CrowdStrike base API URL in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the CrowdStrike integration to sync your data with runZero. ## Requirements {#crowdstrike-requirements} Before you can set up the CrowdStrike integration: - Make sure you have access to the CrowdStrike admin portal. ## Step 1: Configure CrowdStrike to allow API access to runZero 1. Sign in to CrowdStrike. 2. Go to **Support > API Clients and Keys**. When the **API Key** page appears, choose to add a new API client. 3. Provide the following details for the API client: - **Client name**: API client name, such as runZero. - **API scope**: - To ingest host details, include read permissions for **Hosts** and **Host Groups**. - To ingest vulnerability data, include read permissions for **Vulnerabilities**. - To ingest software data, include read permissions for **Assets**. 4. When you are done, add the client. An API client created window appears and shows you the client ID and client secret. You'll need them to configure the integration in runZero. 5. Copy the client ID and client secret now. You may not be able to get them later. ## Step 2: Add the CrowdStrike credentials to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `CrowdStrike Falcon`. 2. Choose **CrowdStrike Falcon API key** from the list of credential types. 3. Provide the following information: - **CrowdStrike client ID and CrowdStrike client secret** - To generate your client ID and client secret, go to **Support > API Clients and Keys > OAuth2 API clients > Add new API Client** in your CrowdStrike portal. - **CrowdStrike API URL** - Your organization-specific base URL, which will depend on your account type. You can find this in the CrowdStrike API Swagger documentation. - For a **US-1** account use `api.crowdstrike.com` - For a **US-2** account use `api.us-2.crowdstrike.com` - For a **US-GOV-1** account use `api.laggar.gcw.crowdstrike.com` - For a **EU-1** account use `api.eu-1.crowdstrike.com` 4. If you want other organizations to be able to use these credentials, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 5. Save the credentials. You're now ready to set up and activate the connection to bring in data from CrowdStrike. ## Step 3: Choose how to configure the CrowdStrike integration The CrowdStrike integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the CrowdStrike integration to sync data After you add your CrowdStrike credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the CrowdStrike integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new CrowdStrike-only assets are created. 1. Activate a [connection to CrowdStrike](https://console.runzero.com/ingest/crowdstrike). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure that it has access to the organization you are currently in. 3. Set the severity and risk levels you want to import (optional). 4. Set the _Fingerprint only_ toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 5. Add an [filter](#crowdstrike-filtering) for imported assets (optional).
If the Crowdstrike API key is configured with access to Falcon Discover or Falcon Spotlight, software and vulnerability data will only be imported for the assets included in the filtered results.
6. Enter a name for the task, like `CrowdStrike sync` (optional). 7. Choose the Explorer to perform this connector task from (optional). 8. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 9. Enter a description for the task (optional). 10. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the _Exclude unknown assets_ toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the CrowdStrike integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the CrowdStrike toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the CrowdStrike toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View CrowdStrike assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your CrowdStrike assets and vulnerabilities. These will have a CrowdStrike icon listed in the **Source** column. To filter by CrowdStrike attributes, consider running the following queries: - [View all CrowdStrike assets](https://console.runzero.com/inventory?search=source%3Acrowdstrike) ``` source:crowdstrike ``` - [Find assets that have a CrowdStrike EDR agent installed](https://console.runzero.com/inventory?search=edr.name%3ACrowdStrike) ``` edr.name:crowdstrike ``` - [Find Windows assets, excluding servers, that are missing a CrowdStrike EDR agent](https://console.runzero.com/inventory?search=os%3Awindows%20and%20not%20type%3Aserver%20and%20not%20edr.name%3Acrowdstrike) ``` os:windows and not type:server and not edr.name:CrowdStrike ``` - [View all CrowdStrike vulnerabilities](https://console.runzero.com/inventory/vulnerability?search=source%3Acrowdstrike) ``` source:crowdstrike ``` - [View all CrowdStrike software results](https://console.runzero.com/inventory/software?search=source%3Acrowdstrike) ``` source:crowdstrike ``` Click into each asset or vulnerability to see its individual attributes. runZero will show you the attributes returned by the CrowdStrike API, with the exception of policies. ## Filtering Crowdstrike assets {#crowdstrike-filtering} An optional filter can be applied to Crowdstrike integration tasks. runZero uses Crowdstrike's Falcon Query Language (FQL) for filtering. FQL follows the syntax `:[operator]`. Multiple expressions can be combined for more complex filtering by adding a `+` between expressions. An OR expression can also be leveraged with comma separated expressions. ### Properties {#crowdstrike-filtering-properties} The following are some useful CrowdStrike properties that can be used in an FQL expression to filter assets. Details on additional attributes that are available for filtering can be found by reviewing [CrowdStrike's API documentation](https://falcon.crowdstrike.com/documentation/46/crowdstrike-oauth2-based-apis). | CrowdStrike Property | runZero Attribute | Description | Example | | -------------------- | ----------------- | --------------------------------------------------------------- | -------------------- | | `external_ip` | externalIP | The external IP address of the device | 18.191.169.203 | | `first_seen` | firstSeen | A timestamp of when the device was first seen by CrowdStrike | 2022-01-08T19:42:34Z | | `hostname` | hostname | The hostname of the device | EXPLORER-01 | | `last_seen` | lastSeen | The timestamp of when the device was last seen by CrowdStrike | 2022-09-13T19:14:30Z | | `local_ip` | localIP | The local IP address of the device | 192.168.1.100 | | `mac_address` | macAddress | The mac address of the interface communication with CrowdStrike | 0a-6e-20-4a-e6-56 | | `os_version` | osVersion | The operation system version of the device | Ubuntu 20.04 | | `platform_name` | platformName | The platform running on the device | Linux | | `product_type_desc` | productTypeDesc | The type of device | Server | ### Operators {#crowdstrike-filtering-operators} The following operators can be used in an FQL expression to filter assets. | Operator | Description | | -------- | --------------------------------------------------------------------------------- | | ! | Not equal to | | > | Greater than | | >= | Greater than or equal to | | < | Less than | | <= | Less than or equal to | | ~ | Text match. Tokenizes the string, ignoring spaces, case and punctuation | | !~ | Does not text match. Tokenized the string, ignoring spaces, cases and punctuation | | * | Wildcard matching. Matches one or more characters | ### Example Filters {#crowdstrike-filtering-examples} The following are examples of filters that can be applied to the CrowdStrike sync. | Search Filter | Description | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `hostname:'WIN10*'` | Import all devices where the hostname starts with WIN10 | | `platform_name:'Linux'` | Import all Linux devices | | `product_type_desc:'Server'` | Import all devices that CrowdStrike identifies as a Server | | `hostname:'PROD*'+platform_name:'Linux'` | Import all Linux devices with a hostname that starts with PROD | | `local_ip:'192.168.1.100'` | Only import the device with a local IP address of 192.168.1.100 | | `local_ip:!'192.168.1.100'` | Import all devices, excluding 192.168.1.100 | | `local_ip.raw:*'192.168.1.*'` | Import all devices with a local IP address in the 192.168.1.0/24 range | | `(local_ip.raw:*'192.168.1.*'),(local_ip.raw:*'192.168.2.*')` | Import all devices with a local IP address in the 192.168.1.0/24 or 192.168.2.0/24 range | | `local_ip.raw:!*'192.168.1.*'` | Import all devices, excluding devices with a local IP address in the 192.168.1.0/24 range | | `local_ip.raw:!*'192.168.1.*'+local_ip.raw:!*'192.168.2.*'` | Import all devices, exluding devices with a local IP in the 192.168.1.0/24 and 192.168.2.0/24 ranges | ## Troubleshooting {#crowdstrike-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the CrowdStrike integration unable to connect? 1. Are you getting any data from the Crowdstrike integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the CrowdStrike integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. If the integration endpoint is on-premises, verify they are running the integration task from an Explorer with access to the CrowdStrike host. ### How can I solve the following CrowdStrike error? `Unable to collect software data for CrowdStrike devices: invalid response 403 Forbidden` This error occurs if your API client is missing the **Assets** API scope. The integration requires read-only permissions for **Assets** in order to collect software information. Host and vulnerability data should be collected just fine, though. This can be remedied by returning to [step 1](#step-1-configure-crowdstrike-to-allow-api-access-to-runzero) of the CrowdStrike documentation above and enabling read permissions for **Assets**. --- docs/custom-integration-scripts.md --- title: "Custom Integration Scripts" --- To set up the ((custom integration)) script, you will need to: 1. Write the script. 1. Optionally add credentials. 1. Create an integration task. ## Step 1: Write integration script The script can be written in [((Starlark))](https://github.com/google/starlark-go/blob/master/doc/spec.md#starlark-in-go-language-definition), a Python-like language with some notable differences: 1. There is no exception handling (`try/catch`) 1. There is no f-string `f'{var}'` formatting - `"{}".format(var)` is the supported method of string interpolation. ### Step 1a: Entrypoint The ((script)) needs an entrypoint, a function that gets called by the runZero service and returns the Inventory Assets discovered by the script. 1. The entrypoint must accept a variadic `*args` and `**kwargs` for parameters to be passed in. 1. The entrypoint must return a `list` of `ImportAsset`s to be imported. 1. The entrypoint (function name) of the script will default to `main`, but can be set depending on the integration type [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). ```python load('runzero.types', 'ImportAsset') def main(*args, **kwargs): asset_one = ImportAsset( id=1, os='custom import os', osVersion='0.0.0.0.0.0.1-pre-alphabetazed', manufacturer='Name of manufacturer', model='Model of asset', ) asset_two = ImportAsset( id=2, os='custom import os 2', osVersion='0.0.0.0.0.0.2-prezed', manufacturer='Name of manufacturer', model='model of asset', ) return [asset_one, asset_two] ``` ## Step 2: Add the custom script Credential to runZero The credential used for the script is a key-value pair passed into the script function as `kwargs` and can be used as username and password or for anything requiring a secret. ```python def main(*args, **kwargs): client_id = kwargs['access_key'] client_secret = kwargs['access_secret'] ``` 1. Go to the [Credentials page](https://console.runzero.com/credentials) in the runZero console and click **Add Credential**. 1. Choose **Custom Script Secret** from the list of credential types. 1. Provide a name for the credential, like `Script Secret` for the service being integrated with. 1. Provide the following information: * **Access Key** - The username or client id that will be passed into the script as a `kwargs` named `access_key`. * **Access Secret** - The secret that will be passed into the script as a `kwargs` named `access_secret`. 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 1. Save the credential. ## Step 3: Create a new task 1. Go to **Tasks**, click the **Integrate** button, and select **Custom Scripts** under **Custom integrations** from the dropdown. 1. Provide a name for the task 1. Select or create a custom integration 1. Select or create credentials for the script 1. Select an explorer * Custom integration scripts must be run on a hosted explorer 1. Select Site, Task description, and Schedule as appropriate. 1. Click Activate Connection to start the task. ## Using the CLI The `runzero` CLI includes a `script` sub-command to help in writing and debugging Starlark scripts that use the [runZero Types](custom-integration-scripts.md#runzero-types) and [Libraries](custom-integration-scripts.md#libraries) outlined below. ### Running scripts Hello World ```python def main(*args, **kwargs): print("Hello world!") ``` Save the file as `print.star` so it can be run from the CLI ```sh $ runzero script --filename print.star Dec 12 12:59:07.099 [INFO] script: Hello world None ``` Running the script with `args` ```python def main(*args, **kwargs): print("Hello {}".format(args[0])) ``` ```sh $ runzero script --filename print.star --args Dave Dec 12 13:01:20.707 [INFO] script: Hello Dave None ``` Running the script with `kwargs` ```python def main(*args, **kwargs): print("Hello {}".format(kwargs["name"])) ``` ```sh runzero script --filename print.star --kwargs name=Dave Dec 12 13:28:56.933 [INFO] script: Hello Dave None ``` `args` and `kwargs` can be called multiple times to pass in as many arguments as needed ```python def main(*args, **kwargs): print("{} {}".format(args[0], args[1])) print("{} {}".format(kwargs["access_key"], kwargs["access_secret"])) ``` ```sh runzero script --filename print.star --args Hello --args Dave --kwargs access_key=foo --kwargs access_secret=bar Dec 12 13:45:50.284 [INFO] script: Hello Dave Dec 12 13:45:50.284 [INFO] script: foo bar None ``` ### REPL The sub-command `script repl` can be useful for larger scripts with multiple functions. The REPL will allow setting variables, calling functions, printing variables, and anything else that can be done in Starlark. ```python runzero script repl --filename print.star >>> main(*("hello", "dave"), **{"access_key": "foo", "access_secret": "bar"}) Dec 12 14:53:42.384 [INFO] script: hello dave Dec 12 14:53:42.384 [INFO] script: foo bar >>> print("Hello {}".format("dave")) Dec 12 14:57:28.961 [INFO] script: Hello dave >>> args = ("hello", "dave") >>> kwargs = {"access_key": "foo", "access_secret": "bar"} >>> main(*args, **kwargs) Dec 12 14:58:57.567 [INFO] script: hello dave Dec 12 14:58:57.567 [INFO] script: foo bar >>> ``` `^D` To exit the REPL ## runZero Types Resource types are implemented in Starlark and are equivalent with the [Python SDK](https://github.com/runZeroInc/runzero-sdk-py) types: * `load('runzero.types', 'ImportAsset', 'NetworkInterface', 'Service', 'ServiceProtocolData', 'Software', 'Vulnerability')` The types can be run from the CLI or loaded into the REPL. ```python runzero script repl --filename print.star >>> load('json', json_encode='encode', json_decode='decode') >>> greeter = json_decode('{"greeting":"hello", "name":"dave"}') >>> print(greeter) Dec 12 15:13:00.971 [INFO] script: {"greeting": "hello", "name": "dave"} >>> ^D ``` ### Libraries runZero provides some additional libraries for basic functionality to make web requests. _Sample usage can be found on the [Starlark library usage examples](custom-integration-starlark-libraries.md) page._ * requests * `load('requests', 'Session', 'Cookie')` * `Session(skip_insecure_verify)` * `skip_insecure_verify` `bool` * Optional: yes * Default: `False` [InsecureSkipVerify](https://pkg.go.dev/crypto/tls#Config) controls whether a client verifies the server's certificate chain and host name. If `skip_insecure_verify` is `True`, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate. * `Cookie` * http * `load('http', http_post='post', http_get='get', http_patch='patch', http_delete='delete', 'url_encode')` * `url_encode({})` * Optional: no * Default: `{}` Key value pairs of url parameters to encode. * `post(url, headers, params, body, timeout, insecure_skip_verify)` * `url` `string` * Optional: yes * Default: `""` (empty String) The url to post to. * `headers` `dict` * Optional: yes * Default: `{}` Headers to send as part of the request. * `params` `dict` * Optional: yes * Default: `{}` URL parameters to add to request. * `body` `bytes` * Optional: yes * Default: None Body of the request. * `timeout`: `int` * Optional: yes * Default: 30 seconds Timeout in seconds for the maximum the request should take. * `insecure_skip_verify` `bool` * Optional: yes * Default `False` [InsecureSkipVerify](https://pkg.go.dev/crypto/tls#Config) controls whether a client verifies the server's certificate chain and host name. If `skip_insecure_verify` is `True`, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate. * `get(url, headers, params, timeout, insecure_skip_verify)` * `url` `string` * Optional: yes * Default: `""` (empty String) The url to post to. * `headers` `dict` * Optional: yes * Default: `{}` Headers to send as part of the request. * `params` `dict` * Optional: yes * Default: `{}` URL parameters to add to request. * `timeout`: `int` * Optional: yes * Default: 30 seconds Timeout in seconds for the maximum the request should take. * `insecure_skip_verify` `bool` * Optional: yes * Default `False` [InsecureSkipVerify](https://pkg.go.dev/crypto/tls#Config) controls whether a client verifies the server's certificate chain and host name. If `skip_insecure_verify` is `True`, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate. * `patch(url, headers, params, body, timeout, insecure_skip_verify)` * `url` `string` * Optional: yes * Default: `""` (empty String) The url to post to. * `headers` `dict` * Optional: yes * Default: `{}` Headers to send as part of the request. * `params` `dict` * Optional: yes * Default: `{}` URL parameters to add to request. * `body` `bytes` * Optional: yes * Default: None Body of the request. * `timeout`: `int` * Optional: yes * Default: 30 seconds Timeout in seconds for the maximum the request should take. * `insecure_skip_verify` `bool` * Optional: yes * Default `False` [InsecureSkipVerify](https://pkg.go.dev/crypto/tls#Config) controls whether a client verifies the server's certificate chain and host name. If `skip_insecure_verify` is `True`, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate. * `delete(url, headers, params, body, timeout, insecure_skip_verify)` * `url` `string` * Optional: yes * Default: `""` (empty String) The url to post to. * `headers` `dict` * Optional: yes * Default: `{}` Headers to send as part of the request. * `params` `dict` * Optional: yes * Default: `{}` URL parameters to add to request. * `body` `bytes` * Optional: yes * Default: None Body of the request. * `timeout`: `int` * Optional: yes * Default: 30 seconds Timeout in seconds for the maximum the request should take. * `insecure_skip_verify` `bool` * Optional: yes * Default `False` [InsecureSkipVerify](https://pkg.go.dev/crypto/tls#Config) controls whether a client verifies the server's certificate chain and host name. If `skip_insecure_verify` is `True`, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate. * net * `load('net', 'ip_address')` * `ip_address` * json * `load('json', json_encode='encode', json_decode='decode')` * `encode` * `decode` * time * `load('time', 'parse_time')` * `parse_time` * uuid * `load('uuid', 'new_uuid')` * `new_uuid` * gzip * `load('gzip', gzip_decompress='decompress', gzip_compress='compress')` * `gzip_decompress` * `gzip_compress` * base64 * `load('base64', base64_encode='encode', base64_decode='decode')` * `base64_encode` * `base64_decode` * crypto * `load('crypto', 'sha256', 'sha512', 'sha1', 'md5')` * `sha256` * `sha512` * `sha1` * `md5` * flatten * `load('flatten_json', 'flatten')` * `flatten` ## Existing Custom Integrations --- docs/custom-integration-starlark-libraries.md --- title: "Starlark library usage examples" --- This document provides sample usage for common runZero Starlark libraries used in custom integration scripts. ## requests {#starlark-lib-requests} ```starlark load('requests', 'Session', 'Cookie') load('json', json_decode='decode') def requests_example(): session = Session() session.headers.set('Accept', 'application/json') session.headers.set('User-Agent', 'Mozilla/5.0') session.headers.set('User-Agent', None) # remove header url = 'https://hacker-news.firebaseio.com/v0/topstories.json' session.cookies.set(url, {"test_cookie": "cookie_value"}) response = session.get(url) if response and response.status_code == 200: data = json_decode(response.body) print("Top story IDs:", data[:5]) else: print("Failed to fetch stories") ``` ## http {#starlark-lib-http} ```starlark load('http', http_post='post', http_get='get', 'url_encode') def fetch_example(): url = "https://hacker-news.firebaseio.com/v0/topstories.json" headers = {"Accept": "application/json"} response = http_get(url, headers=headers) if response and response.status_code == 200: print("Top stories retrieved successfully.") else: print("Request failed with status:", response.status_code) ``` ## net {#starlark-lib-net} ```starlark load('net', 'ip_address') def parse_ip_list(): ips = ["192.168.1.1", "2607:f8b0:4005:805::200e"] for ip in ips: addr = ip_address(ip) print("IP:", addr, "Version:", addr.version) ``` ## json {#starlark-lib-json} ```starlark load('json', json_encode='encode', json_decode='decode') def test_json_handling(): data = {"name": "runZero", "features": ["scan", "API", "integrations"]} encoded = json_encode(data) print("Encoded JSON:", encoded) decoded = json_decode(encoded) print("Decoded:", decoded["name"]) ``` ## time {#starlark-lib-time} ```starlark load('time', 'parse_time') def parse_example_time(): time_str = "2025-05-01T15:00:00Z" parsed = parse_time(time_str) print("Parsed time:", parsed) # Emit Unix epoch time in seconds for use in certain time fields epoch = parsed.unix print("Epoch time:", epoch) ``` ## uuid {#starlark-lib-uuid} ```starlark load('uuid', 'new_uuid') def create_unique_id(): uid = new_uuid() print("Generated UUID:", uid) ``` ## gzip {#starlark-lib-gzip} ```starlark load('gzip', gzip_decompress='decompress', gzip_compress='compress') def gzip_example(): original = "Hello, runZero!".encode("utf-8") # Compress the data compressed = gzip_compress(original) print("Compressed length:", len(compressed)) # Decompress it back decompressed = gzip_decompress(compressed) print("Decompressed value:", decompressed.decode("utf-8")) ``` ## base64 {#starlark-lib-base64} ```starlark load('base64', base64_encode='encode', base64_decode='decode') def b64_example(): username = "xxx" password = "yyy" enc = base64_encode(username + ":" + password) dec = base64_decode(enc) return (enc, dec) ``` ## crypto {#starlark-lib-crypto} ```starlark load('crypto', 'sha256', 'sha512', 'sha1', 'md5') def main(*args, **kwargs): access_key = kwargs['access_key'] access_secret = kwargs['access_secret'] input = "test" sha256_hash = sha256(input) if str(sha256_hash) != '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08': print("sha256_hash [fail]: {}".format(sha256_hash)) else: print("sha256_hash [pass]: {}".format(sha256_hash)) sha512_hash = sha512(input) if str(sha512_hash) != 'ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff': print("sha512_hash [fail]: {}".format(sha512_hash)) else: print("sha512_hash [pass]: {}".format(sha512_hash)) sha1_hash = sha1(input) if str(sha1_hash) != 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3': print("sha1_hash [fail]: {}".format(sha1_hash)) else: print("sha1_hash [pass]: {}".format(sha1_hash)) md5_hash = md5(input) if str(md5_hash) != '098f6bcd4621d373cade4e832627b4f6': print("md5_hash [fail]: {}".format(md5_hash)) else: print("md5_hash [pass]: {}".format(md5_hash)) return True ``` ## flatten (json) {#starlark-lib-flatten-json} ```starlark load('flatten_json', 'flatten') def main(*args, **kwargs): nested_json = {"foo": "bar", "a": {"b": "c"}} flattened_json = flatten(nested_json) return True ``` --- docs/dragos.md --- title: Dragos --- runZero integrates with ((Dragos)) to help expand your OT visibility by importing assets and vulnerabilities from the Dragos API. ## Getting started with Dragos {#dragos-getting-started} To set up an integration with Dragos, you'll need to: 1. Generate a Dragos API ID and API Secret with the following privileges: * asset:read * detection:read * vulnerability:read 1. Configure the Dragos credential in runZero. 1. Activate the integration to pull your data into runZero. ## Step 1: Generate a Dragos API ID and API Secret {#dragos-step1} 1. Log into the Dragos console and navigate to Admin, then navigate to Users. Under the user, click the Add New API Key button. 1. When the Generate New API Key box appears, name your API ID and API Secret, then click Generate Key. 1. Copy the ID and Secret for later. ## Step 2: Add the Dragos API ID and API Secret to runZero {#dragos-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. 1. Choose **Dragos API ID & Secret** from the list of credential types. 1. Provide a name for the credential, like `Dragos`. 1. Provide the following information: * **Dragos API ID** - Your Dragos API ID from Step 1. * **Dragos API Secret** - Your Dragos API Secret from Step 1. * **Dragos API URL** - The URL to your Dragos instance, without any trailing slashes. For example, `https://my.instance.dragos.cloud`. * **Insecure** - Enable this option to approve authenticating with untrusted endpoints. When enabled, certificate validation is disabled. Use with caution. 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 1. Verify and save the credential. Note that if the URL provided is an internal IP address, verification is unsupported, but the credential can be saved and the integration will still be usable when run on an Explorer. You're now ready to set up and activate the connection to bring in data from Dragos. ## Step 3: Choose how to configure the Dragos integration {#dragos-step3} The Dragos integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#dragos-step4} After you add your Dragos credential, you'll need to sync your data from Dragos. ### Step 4a: Configure the Dragos integration as a connector task {#dragos-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Dragos-only assets are created. 1. Activate a connection to [Dragos](https://console.runzero.com/ingest/dragos). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Enter a name for the task, like `Dragos Sync` (optional). 1. Enter a description for the task (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. If you want to exclude assets that have not been scanned by runZero from your integration import, select the **Exclude assets that cannot be merged into an existing asset** option. By default, the integration will include assets that have not been scanned by runZero. 1. If you want to skip importing vulnerabilities detected on Dragos assets, select the **Disable importing vulnerabilities from the Dragos inventory** option. By default, the integration will import both assets and vulnerabilities. 1. Choose the combination of **Priorities**, **Severities**, **Tags**, and **Subnets** criteria to filter assets by. These criteria correspond to the available filter criteria within Dragos. 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Dragos integration as a scan probe {#dragos-step4b} You can run the Dragos integration as a scan probe so that the runZero Explorer will pull your Dragos assets into the runZero Console. In a new or existing scan configuration: * Ensure that the _DRAGOS_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct _DRAGOS_ credential to _Yes_ in the _Credentials_ tab. ## Step 5: View Dragos assets {#dragos-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Dragos assets. These assets will have a Dragos icon listed in the **Source** column. To filter by Dragos assets, consider running the following queries: * [View all Dragos assets](https://console.runzero.com/inventory?search=source%3Adragos): ``` source:Dragos ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from Dragos. --- docs/google-cloud-platform.md --- title: "Google Cloud Platform" aliases: [ "/docs/gcp/" ] --- The ((Google Cloud Platform)) (((GCP))) integration provides visibility into your cloud assets by synchronizing your GCP cloud inventories with runZero. runZero also integrates with other cloud providers, such as [Microsoft Azure](azure.md) and [Amazon AWS](aws.md). Similarly to other integrations, you will need to add the [Scanning with credentials](scanning-credentials.md) needed to authenticate to GCP and set up a connector in runZero. runZero will pull in GCP compute instance VMs, pulling in GCP attributes that will be viewable from each asset. The following GCP asset types are supported: - Compute Engine instances - Load balancers - Cloud SQL ## Requirements {#gcp-requirements} - Verify you have a [Google Cloud service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating) with the `Compute Network Viewer` and `Cloud SQL Viewer` [roles](https://cloud.google.com/iam/docs/understanding-roles). - This service account will need to be granted access to each project that you want the integration to gather data from. - [Download a key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) for the GCP service account. - Verify you have these [GCP APIs enabled](https://cloud.google.com/endpoints/docs/openapi/enable-api) on each project: - Compute Engine - Cloud SQL Admin ## How to set up the Google Cloud Platform integration Here are the high-level steps to set up the Google Cloud Platform integration: - [Create a Google Cloud Platform credential](#step-1-create-google-cloud-platform-credentials) in runZero. - Choose whether to configure the integration as [a scan probe or connector task](#step-2-choose-how-to-configure-the-gcp-integration). - [Activate the integration](#step-3-activate-the-google-cloud-platform-integration) for Google Cloud Platform. - [View your GCP assets](#step-4-view-your-google-cloud-platform-assets). ## Step 1: Create Google Cloud Platform credentials 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) and click **Add Credential**. 2. From the **Credentials type** dropdown, choose **GCP Service Account Key**. 3. Provide a name for the credential, like `GCP`. 4. Set the **Include all projects** toggle to _Yes_ if you want runZero to gather asset data from all GCP projects that the service account has access to. If set to _No_, the integration will only gather asset data from the project specified in the key file. 5. Click **Choose file** to upload the service account key file you downloaded from GCP. 6. If you want other organizations to be able to use this credential, select the **Make this a global credential** option. Otherwise, you can configure access on a per-organization basis. 7. Save the credential. You're now ready to set up and activate the connection to bring in data from Google Cloud Platform. ## Step 2: Choose how to configure the GCP integration The GCP integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 3: Activate the Google Cloud Platform integration After you add your GCP credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 3a: Configure the GCP integration as a connector task 1. [Activate a connection to GCP](https://console.runzero.com/ingest/gcp/). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. Enter a name for the task, like `Google Cloud Platform sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. To organize your assets logically, choose the site you'd like to use to add your assets to. You can choose an existing site or add them to a new site when the sync occurs. Assigning your assets to a site helps organize and group your assets. You can automatically generate a new site per GCP project by selecting this option from the task configuration. 6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 7. Activate the connection when you are done. The sync will run on the defined schedule. You can check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 3b: Configure the GCP integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the GCP toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the GCP toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 4: View your Google Cloud Platform assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your GCP assets. These assets will have a Google icon listed in the **Source** column. To filter by GCP assets, consider running the following queries: * [View all GCP assets](https://console.runzero.com/inventory?search=source%3Agcp): ``` source:gcp ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by GCP. ## Troubleshooting {#gcp-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Google Cloud Platform integration unable to connect? 1. Are you getting any data from the GCP integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the GCP integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/google-workspace.md --- title: Google Workspace --- runZero integrates with ((Google Workspace)) to allow you to sync and enrich your asset inventory, as well as gain visibility into users and groups. Adding your Google Workspace data to runZero makes it easier to find unmanaged assets on your network. The Google Workspace integration supports ChromeOS, Mobile, and Endpoint [registered asset types](https://cloud.google.com/asset-inventory/docs/supported-asset-types). ## Requirements {#googleworkspace-requirements} * Verify or create a new [Google service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating) in whichever project is most suitable. * [Create and download a key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) for the Google service account. Save this JSON file. * Verify that you have the `Admin SDK` and `Cloud Identity` APIs enabled for the project. Use the search box in the [API Library](https://console.cloud.google.com/apis/library) to find each API and then enable it. * Enable domain-wide delegation in the [Google Workspace console](https://admin.google.com/ac/owl/domainwidedelegation) * Add a new API client using the unique numeric ID of service account as the Client ID * Enable the following OAuth scopes for this API client: ``` https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.device.mobile.readonly, https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly, https://www.googleapis.com/auth/cloud-identity.devices.readonly ``` * Optionally, enter each OAuth scope individually: * `https://www.googleapis.com/auth/admin.directory.user.readonly` * `https://www.googleapis.com/auth/admin.directory.group.readonly` * `https://www.googleapis.com/auth/admin.directory.device.mobile.readonly` * `https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly` * `https://www.googleapis.com/auth/cloud-identity.devices.readonly` ## How to set up the Google Workspace integration These are the high-level steps to set up the Google Cloud Platform integration: * [Create a Google Workspace credential](#step-1-create-a-google-workspace-credential) in runZero. * Choose whether to configure the integration as [a scan probe or connector task](#step-2-choose-how-to-configure-the-google-workspace-integration). * [Activate the connection](#step-3-activate-the-google-workspace-integration) for Google Workspace. * [View your results](#step-4-view-google-workspace-assets). ## Step 1: Create a Google Workspace credential 1. Go to the [Credentials page](https://console.runzero.com/credentials) and click **Add Credential**. 2. From the **Credentials type** dropdown, choose **Google Workspace Client Secret**. 3. Provide a name for the credential, like `Google Workspace`. 4. In the _Admin account email_ field, provide the email address of an administrator account with access to the assets, users, or groups you wish to import. 5. If you want to import from an organization other than the one your administrator account belongs to, provide a _Customer ID_. By default, runZero will use the Customer ID associated with the service account. (Optional) 6. Click **Choose file** to upload the service account key file you downloaded from Google Workspace. 7. If you want other organizations to be able to use this credential, select the **Make this a global credential** option. Otherwise, you can configure access on a per-organization basis. 8. Save the credential. You're now ready to set up and activate the connection to bring in data from Google Workspace. ## Step 2: Choose how to configure the Google Workspace integration The Google Workspace integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. Configuring the integration as a scan probe is useful if you are running self-hosted runZero Platform and your console cannot access Google Workspace. For most situations it will be easier to set up a scheduled connection to sync your data from Google Workspace. ## Step 3: Activate the Google Workspace integration After you add your GCP credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 3a: Configure the Google Workspace integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where the data is organized. 1. [Activate a connection to Google Workspace](https://console.runzero.com/ingest/googleworkspace/). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. Enter a name for the task, like `Google Workspace sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. To organize your assets logically, choose the site you'd like to use to add your assets to. You can choose an existing site or add them to a new site when the sync occurs. Assigning your assets to a site helps organize and group your assets. 6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 7. Activate the connection when you are done. The sync will run on the defined schedule. You can check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 3b: Configure the Google Workspace integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the GoogleWorkspace toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the GoogleWorkspace toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 4: View Google Workspace assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Google Workspace assets. These assets will have a Google Workspace icon listed in the **Source** column. To filter by Google Workspace assets, consider running the following queries: * [View all Google Workspace assets](https://console.runzero.com/inventory?search=source%3Agoogleworkspace): ``` source:googleworkspace ``` * [View runZero assets not connected to Google Workspace](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Agoogleworkspace): ``` source:runzero AND NOT source:googleworkspace ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by Google Workspace.

The Google Workspace integration provides details about users and groups in addition to enriching asset inventory data. Go to Inventory > Users or Inventory > Groups to view the data provided by Google Workspace. Use the query source:googleworkspace to filter your results.

## Troubleshooting {#google-workspace-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Google Workspace integration unable to connect? 1. Are you getting any data from the Google Workspace integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Google Workspace integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/microsoft-365-defender.md --- title: Microsoft 365 Defender --- runZero integrates with ((Microsoft 365 Defender)) to allow you to sync and enrich your asset, software, and vulnerability inventory. Adding your ((Microsoft 365)) ((Defender)) data to runZero makes it easier to find assets missing EDR protection. ## Getting started {#microsoft-365-defender-getting-started} To set up the Microsoft 365 Defender integration, you'll need to: 1. Configure Microsoft 365 Defender to allow API access through runZero. 2. Add the Microsoft 365 Defender credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Microsoft 365 Defender integration to sync your data with runZero. ## Requirements {#microsoft-365-defender-requirements} Before you can set up the Microsoft 365 Defender integration: * Make sure you have access to the Microsoft Azure portal. ## Step 1: Register an Azure application for Microsoft 365 Defender API access {#microsoft-365-defender-api-access} runZero can authenticate to the Microsoft 365 Defender API using a client secret. Register an application to configure Microsoft 365 Defender API access. 1. Sign in to the Microsoft Azure portal. 2. Go to _App registrations_ and click on _+ New registration_. * Provide a name. * Select the supported account types. * Optionally add a redirect URI. 3. Click _Register_ to register the application. 4. Once the application is created, you should see the Overview dashboard. Note the following information: * Application (client) ID * Directory (tenant) ID 5. From the application's details page, go to _Manage > API permissions_ and choose _+ Add a permission_. 6. Select the second tab called _APIs my organization uses_ to view available APIs. 7. Select `WindowsDefenderATP` from the list of Microsoft APIs. 8. Select the permissions type `Application permissions` to configure a _client secret_. 9. Search for and select the following required permissions: * Windows Defender ATP API permissions: * `Machine.Read.All` * `Software.Read.All` * `Vulnerability.Read.All` 10. Click _Add permissions_ to save the permissions to the application. 11. Click _Grant admin consent_ to grant consent for the permissions to the application. 12. To generate the client secret, perform the following steps from the app management pages: * Navigate to _App registrations_ and select the application you created. * Go to _Certificates & secrets_ and click on _+ New client secret_. * Enter a description. * Select the expiration. * Click _Add_ to create the client secret and save the client secret value. ## Step 2: Add an Azure Client Secret credential to runZero {#microsoft-365-defender-credential} This type of credential can be used to sync all resources in a single directory (across multiple subscriptions). 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_. 2. Provide a name for the credential, like `Azure Client Secret`. 3. Choose _Azure Client Secret_ from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure client secret** - To generate a client secret, go to _App registrations_, select your application, go to _Manage > Certificates & secrets_ and click on _New client secret_. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ## Step 3: Choose how to configure the Microsoft 365 Defender integration The Microsoft 365 Defender integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the Microsoft 365 Defender integration to sync data After you add your Microsoft 365 Defender credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the Microsoft 365 Defender integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Microsoft 365 Defender-only assets are created. 1. Activate a [connection to Microsoft 365 Defender](https://console.runzero.com/ingest/ms365defender). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure it has access to the organization you are currently in. 3. Enter a name for the task, like `Microsoft 365 Defender sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**, choose the site you want to add your assets to. 6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 7. If you want to include assets that have stopped reporting to the Microsoft 365 Defender service in your integration import, switch the **Include inactive assets** toggle to _Yes_. By default, the integration will not include assets that are marked as inactive. 8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Microsoft 365 Defender integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the Defender365 toggle to `Yes`, and change any of the default options if needed. 4. On the Credentials tab, set the MS365Defender toggle for the credential you wish to use to `Yes`. 5. Click _Initialize scan_ to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View Microsoft 365 Defender assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Microsoft 365 Defender assets. These assets will have an Active Directory icon listed in the **Source** column. To filter by Microsoft 365 Defender assets, consider running the following queries: * [View all Microsoft 365 Defender assets](https://console.runzero.com/inventory?search=source%3Ams365defender): ``` source:ms365defender ``` * [View runZero assets not connected to Microsoft 365 Defender](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Ams365defender): ``` source:runzero AND NOT source:ms365defender ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by Microsoft 365 Defender. ## Filtering Microsoft 365 Defender assets {#microsoft-365-defender-filtering} An optional filter can be applied to Microsoft 365 Defender integration tasks. runZero uses Microsoft Graph $filter query paramater to filter assets. GraphQL follows the syntax ` [operator] `. Multiple expressions can be combined for more complex filtering by adding an `and` or `or` between expressions. ### Properties {#microsoft-365-defender-filtering-properties} Any property that runZero imports from Microsoft 365 Defender can be used to apply a filter. The following are some examples. | Defender Property | runZero Attribute | Description | Example | | ------------------- | ----------------------------------- | --------------------------------------------------------------------- | ------------------- | | `computerDNSName` | @ms365defender.dev.computerDNSname | The hostname of the device | EXPLORER-01 | | `osPlatform` | @ms365defender.dev.osPlatform | The operation system of the device | Windows11, Android | | `heatlhStatus` | @ms365defender.dev.heatlhStatus | The health status of the Defender agent that is installed | Active, Inactive | | `isAADJoined` | @ms365defender.dev.isAADJoined | Boolean value specifying whether the device is registered in Azure AD | true, false | | `managedBy` | @ms365defender.dev.managedBy | Description of how the device is managed | Intune ### Operators {#microsoft-365-defender-filtering-operators} The following are common operators that can be used in a Microsoft 365 Defender filter. - Equal to (`eq`) - Not equal to (`ne`) - Has (`has`) - Less than (`lt`) - Greather than (`gt`) - Less than or equal to (`le`) - Greater than or equal to (`ge`) The following are common functions that can be used in a Microsoft 365 Defender filter. Functions follow the syntax `function(, )`. - Starts with (`startswith`) - Ends with (`endswith`) - Contains (`contains`) ### Example Filters {#microsoft-365-defender-filtering-examples} The following are examples of filters that can be applied to a Microsoft 365 Defender integration. | Search Filter | Description | | ------------------------------------------------------------| -----------------------------------------------------------------------| | `not(osPlatform eq 'Android')` | Import all assets except those with an Android operating system | | `not(osPlatform eq 'Android') and not(osPlatform eq 'iOS')` | Import all assets execpt those with an Android or iOS operating system | | `startswith(computerDNSname, 'PROD')` | Import all devices with a hostname that starts with PROD | | `not(startswith(computerDNSname, 'DEV'))` | Import all devices except those with a hostname that starts with DEV | ## Troubleshooting {#m365defender-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Microsoft 365 Defender integration unable to connect? 1. Are you getting any data from the Microsoft 365 Defender integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Microsoft 365 Defender integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/microsoft-active-directory.md --- title: Microsoft Active Directory aliases: ["/docs/ldap/"] --- runZero integrates with Microsoft Active Directory (AD) via ((LDAP)) to allow you to sync and enrich your asset inventory, as well as gain visibility into domain users and groups. Adding your AD data to runZero makes it easier to find assets that are not part of your domain. ## Getting started {#ldap-getting-started} To set up the Active Directory integration, you'll need to: 1. Add the AD credential in runZero. 2. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 3. Activate the Active Directory integration to sync your data with runZero. ## Requirements {#ldap-requirements} Before you can set up the LDAP integration, make sure you have credentials for an LDAP account. ## Step 1: Add the LDAP credential to runZero 1. Go to the [Add credential page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `LDAP`. 2. Choose **LDAP Username & Password** from the list of credential types. 3. Provide the following information: * **LDAP username** - The username you want to use with the LDAP integration. The account used for this integration does not require any special permissions. The following username formats are accepted: * Distinguished Name (DN): `CN=[username],CN=Users,DC=[domain],DC=[tld]` * User Principle Name (UPN): `[username]@[domain].[tld]` * Domain\Username: `[domain]\[username]` * **LDAP password** - The password for the username to be used with the LDAP integration. * **LDAP base DN** - The base distinguished name for LDAP searches. This field requires distinguished name format: `DC=[domain],DC=[tld]`. Note that only entities underneath the specified base DN will be imported into runZero. * **LDAP URL** - The URL for your LDAP server. This field supports `IP[:port]` notation as well as `hostname.domain.tld[:port]`. This field requires that the URL entered begins with `ldap://` (for insecure LDAP connections) or `ldaps://` (for secure LDAP connections). For example: `ldaps://ad.example.com:636` * **LDAP insecure** - Set this to _Yes_ if you want to attempt authentication without a verified thumbprint. By default, runZero will attempt to connect with LDAPS but will fall back to LDAP+StartTLS then LDAP. LDAP without StartTLS will only work if this toggle is set to _Yes_. * **LDAP thumbprints** (optional) - A set of `IP[:port]=SHA256:B64HASH` or `hostname.domain.tld=SHA256:B64HASH` pairs to trust for authentication. * You will need to scan your LDAP server with runZero in order to obtain the TLS thumbprint. The [TLS fingerprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=tls.fp.sha256&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20[tls.fp.sha256]) lists all previously seen fingerprints. The TLS thumbprints used for self-signed certificates will only work with LDAPS. If you want to use LDAP+StartTLS with a self-signed certificate, you will need to set the **Insecure** option to `Yes`. * If _LDAP insecure_ is set to _No_ and no thumbprints are provided: * With a self-signed certificate, the connection will fail because the certificate chain cannot be verified. * With a valid certificate from a public CA, the connection will work without thumbprints. 4. If you want all other organizations to be able to use this credential, select the **Make this a global credential** option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from LDAP. ## Step 2: Choose how to configure the Active Directory integration The Active Directory integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 3: Set up and activate the Active Directory integration to sync data After you add your Active Directory credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 3a: Configure the Active Directory integration as a connector task After you add your LDAP credential, you'll need to set up a connection to sync your data from LDAP. A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new LDAP-only assets are created. 1. Activate a [connection to Active Directory](https://console.runzero.com/ingest/ldap). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Enter a name for the task, like `LDAP sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**, choose the site you want to add your assets to. 6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 7. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 3b: Configure the Active Directory integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the LDAP toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the LDAP toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 4: View Active Directory assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your LDAP assets. These assets will have an Active Directory icon listed in the **Source** column. To filter by LDAP assets, consider running the following queries: * [View all LDAP assets](https://console.runzero.com/inventory?search=source%3Aldap): ``` source:ldap ``` * [View runZero assets not connected to LDAP](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Aldap): ``` source:runzero AND NOT source:ldap ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by LDAP.

The LDAP integration provides details about users and groups in addition to enriching asset inventory data. Go to Inventory > Users or Inventory > Groups to view the data provided by LDAP.

## Troubleshooting {#microsoft-ad-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Microsoft Active Directory integration unable to connect? 1. Are you getting any data from the Microsoft Active Directory integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Microsoft Active Directory integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Microsoft Active Directory host. --- docs/azure.md --- title: Microsoft Azure aliases: ["/docs/set-up-azure/"] --- runZero integrates with ((Microsoft Azure)) to deliver greater visibility into your cloud assets. This integration imports data through each applicable API to enrich your asset inventory: * [Virtual Machines API](https://docs.microsoft.com/en-us/rest/api/compute/virtual-machines) * [Virtual Machine Scale Sets API](https://docs.microsoft.com/en-us/rest/api/compute/virtual-machine-scale-sets) * [Load Balancers API](https://docs.microsoft.com/en-us/rest/api/load-balancer/load-balancers) * [AzureSQL API](https://docs.microsoft.com/en-us/rest/api/sql/) * [Web Apps API](https://docs.microsoft.com/en-us/rest/api/appservice/web-apps) Syncing with Azure allows you to view information about your asset's OS profile, storage profile, and more. This integration imports assets that are in a running state. ## Getting started {#azure-getting-started} The following Azure resource types are supported: * Virtual Machines * Virtual Machine Scale Sets * Azure SQL * Azure Cosmos DB * Load Balancers * Function Apps To set up the Azure integration, you'll need to: 1. Configure Azure to allow API access through runZero. 2. Add an Azure credential to runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Azure integration to sync your data with runZero. ## Requirements {#azure-requirements} Before you can set up the Azure integration, make sure you have access to the Microsoft Azure portal. ## Step 1: Configure Azure to allow API access through runZero 1. Sign in to the Microsoft Azure portal. 2. Go to **Azure Active Directory > App registrations** and click on **New registration**. * Provide a name. * Select the supported account types. * Optionally add a redirect URI. 3. Click **Register** to register the application. 4. Once the application is created, you should see the **Overview** dashboard. Save the following information: * Application (client) ID * Directory (tenant) ID 5. Give the client access to the subscriptions you want to sync. From the subscription details page, go to **Access Control (IAM)** and select **Add > Add role assignment**. Enter the following: * Role: Reader * Assign access to: User, group, or service principal * Under **Select**, search for the name of the application you created. Click on your application to add it to the **Selected members** list below. 6. Click **Save** to save the role assignment. 7. Navigate to **Azure Active Directory > App registrations** and select the application you created. 8. Go to **Certificates & secrets** and click on **New client secret**. * Enter a description. * Select the expiration. 9. Click **Add** to create the client secret. Save the following information: * Client secret value ## Step 2: Add the Azure credential to runZero The credential used for the Azure integration can be either a client secret or a username & password. ### Step 2a: Add an Azure Client Secret credential to runZero This type of credential can be used to sync all resources in a single directory (across multiple subscriptions). 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click **Add Credential**. 2. Provide a name for the credential, like `Azure Client Secret`. 3. Choose **Azure Client Secret** from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to **Azure Active Directory > App registrations** and select the application. * **Azure client secret** - To generate a client secret, go to **Azure Active Directory > App registrations**, select your application, go to **Certificates & secrets** and click on **New client secret**. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to **Azure Active Directory > App registrations** and select the application. * Enable the **All subscriptions** option to sync all resources in your directory. If enabled, you can add subscription IDs to the **Exclude subscription IDs** text area to exclude specific IDs. If disabled, you can add specific subscription IDs by entering them in the **Include subscription IDs** text area. The subscription ID can be found in the Azure portal if you go to **Subscriptions** and select the subscription. For both of these text areas, please enter one subscription ID per line. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ### Step 2b: Add an Azure Username & Password credential to runZero This type of credential can be used to sync all resources across directories. Alternatively, you can add one **Azure Client Secret** credential for each Azure directory you want to sync. 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click **Add Credential**. 2. Provide a name for the credential, like `Azure User/Pass`. 3. Choose **Azure Username & Password** from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to **Azure Active Directory > App registrations** and select the application. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to **Azure Active Directory > App registrations** and select the application. * **Azure username** - The username for your Azure cloud account. This cannot be a federated user account. * **Azure password** - The password for your Azure cloud account. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ## Step 3: Choose how to configure the Azure integration The Azure integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the Azure integration to sync data After you add your Azure credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the Azure integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Azure-only assets are created. 1. Activate a [connection to Azure](https://console.runzero.com/ingest/azure). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. Enter a name for the task, like `Azure sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**, choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 6. Under **Service options**, select the services you would like to sync data from. You must choose at least one. 7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Azure integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the Azure toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the Azure toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View Azure assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Azure assets. These assets will have an Azure icon listed in the **Source** column. To filter Azure assets, consider running the following queries: * [View all Azure assets](https://console.runzero.com/inventory?search=source%3Aazure): ``` source:azure ``` * [View all Azure VMs](https://console.runzero.com/inventory?search=has%3A%22%40azure.vm.vmID%22) ``` has:"@azure.vm.vmID" ``` * [View all Azure virtual machine scale set VMs](https://console.runzero.com/inventory?search=has%3A%22%40azure.vmss.vmID%22) ``` has:"@azure.vmss.vmID" ``` * [View all Azure load balancers](https://console.runzero.com/inventory?search=has%3A%22%40azure.lb.id%22) ``` has:"@azure.lb.id" ``` * [View all AzureSQL instances](https://console.runzero.com/inventory?search=has%3A%22%40azure.azsql.id%22) ``` has:"@azure.azsql.id" ``` * [View all Azure Cosmos DB instances](https://console.runzero.com/inventory?search=has%3A%22%40azure.cosmos.id%22) ``` has:"@azure.cosmos.id"" ``` * [View all Azure Function Apps](https://console.runzero.com/inventory?search=%40azure.functionapp.kind%3A%22functionapp%22) ``` @azure.functionapp.kind:"functionapp" ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by the Azure APIs. ## Troubleshooting {#azure-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Microsoft Azure integration unable to connect? 1. Are you getting any data from the Microsoft Azure integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Microsoft Azure integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/mecm.md --- title: Microsoft Endpoint Configuration Manager (MECM) --- runZero integrates with ((Microsoft Endpoint Configuration Manager)) (MECM), formerly System Center Configuration Manager (SCCM), by importing data from the MECM MSSQL database. This integration allows you to sync data about your devices from MECM, making it easier to find unmanaged devices in your network. ## Getting started with MECM {#mecm-getting-started} To set up an integration with MECM, you'll need to: 1. Identify or create a database user with read access to the MECM database. 1. Configure the MECM credential in runZero. 1. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 1. Activate the integration to pull your data into runZero. ## Step 1: Identify or create a database user for access to MECM {#mecm-step1} 1. Identify an existing database user with read access to the database. 1. Alternatively, create a dedicated read-only database user for this integration. More details on creating a new database user can be found in Microsoft's documentation - [Create a database user](https://learn.microsoft.com/en-us/sql/relational-databases/security/authentication-access/create-a-database-user?view=sql-server-ver16). ## Step 2: Add the MECM database connection string to runZero {#mecm-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. 1. Choose **MECM Database Connection String** from the list of credential types. 1. Provide a name for the credential, like `MECM`. 1. Provide the database connection string, using one of the following formats: * `Server=host,port;Database=database-name;User Id=user-id;Password=password;` When using this format, the values should not contain a semicolon (;). You can use single or double quotes to escape any special characters. * `sqlserver://username:password@host/instance?database=value¶m=value` 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 1. Save the credential. You're now ready to set up and activate the connection to bring in data from MECM. ## Step 3: Choose how to configure the MECM integration {#mecm-step3} The MECM integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#mecm-step4} After you add your MECM credential, you'll need to sync your data from MECM. ### Step 4a: Configure the MECM integration as a connector task {#mecm-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new assets are created. 1. Activate a connection to [MECM](https://console.runzero.com/ingest/mecm). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Enter a name for the task, like `MECM Sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. Enter a description for the task (optional). 1. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the MECM integration as a scan probe {#mecm-step4b} You can run the MECM integration as a scan probe so that the runZero Explorer will pull your MECM devices into the runZero Console. In a new or existing scan configuration: * Ensure that the _MECM_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct _MECM_ credential to _Yes_ in the _Credentials_ tab. ### Step 5: View MECM assets {#mecm-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your MECM assets. These assets will have a Microsoft icon listed in the **Source** column. To filter by MECM assets, consider running the following queries: * [View all MECM assets](https://console.runzero.com/inventory?search=source%3Amecm): ``` source:mecm ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from MECM. --- docs/microsoft-entra-id.md --- title: Microsoft Entra ID aliases: ["/docs/azure-ad/"] --- runZero integrates with Microsoft ((Entra ID)) (formerly ((Azure AD))) to allow you to sync and enrich your asset inventory, as well as gain visibility into Entra ID users and groups. Adding your Entra ID data to runZero makes it easier to find assets that are not part of your domain. Note that Entra ID is still referred to as Azure AD within the runZero product. ## Getting started {#azure-ad-getting-started} To set up the Entra ID integration, you'll need to: 1. Configure Entra ID to allow API access through runZero. 2. Add the Entra ID credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Entra ID integration to sync your data with runZero. ## Requirements {#azure-ad-requirements} Before you can set up the Entra ID integration, make sure you have access to the Microsoft Azure portal. ## Step 1: Register an Azure application for Entra ID API access {#azure-ad-api-access} runZero can authenticate to the Entra ID API using either a username and password or a client secret. Register an application to configure Entra ID API access. 1. Sign in to the Microsoft Azure portal. 2. Go to _App registrations_ and click _+ New registration_. * Provide a name. * Select the supported account types. * Optionally add a redirect URI. 3. Click _Register_ to register the application. 4. Once the application is created, go back to the main Azure portal page and select _App registrations_. You should be able to find the application you just registered. (It may help to select the _Owned applications_ tab.) Click on the app's name 5. You should see the an overview of the app registration. Note the following information: * Application (client) ID * Directory (tenant) ID 6. Click on the display name of the application to go to its management pages. 7. Select the _Manage > Authentication_ section on the left. Set **Allow public client flows** to _Yes_ and then save the configuration. 8. Go to _API permissions_ and click _+ Add a permission_. 9. Select _Microsoft Graph_ from the list of Microsoft APIs. 10. Select the correct permissions type for your needs: * **Username & password**: select _Delegated permissions_ * **Client secret**: select _Application permissions_ 11. Search for and select the following required permissions: * _Device.Read.All_ * _Group.Read.All_ * _User.Read.All_ 12. Click _Add permissions_ to save the permissions to the application. 13. Click _Grant admin consent_ to grant consent for the permissions to the application. 14. If using a client secret, also perform the following steps: * Navigate to _Azure Active Directory > App registrations_ and select the application you created. * Go to _Certificates & secrets_ and click on _New client secret_. * Enter a description. * Select the expiration. * Click _Add_ to create the client secret and save the client secret value. ## Add the Entra ID credential to runZero {#azure-ad-credential} ### Step 2a: Add an Azure Username & Password credential to runZero {#azure-ad-credential-userpass} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_. 2. Provide a name for the credential, like `Azure Username & Password`. 3. Choose _Azure Username & Password_ from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure username** - The username for your Azure cloud account. This cannot be a federated user account. * **Azure password** - The password for your Azure cloud account. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ### Step 2b: Add an Azure Client Secret credential to runZero {#azure-ad-credential-clientsecret} This type of credential can be used to sync all resources in a single directory (across multiple subscriptions). 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_. 2. Provide a name for the credential, like `Azure Client Secret`. 3. Choose _Azure Client Secret_ from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure client secret** - To generate a client secret, go to _App registrations_, select your application, go to _Certificates & secrets_ and click on _+ New client secret_. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application. * Select the **Access all subscriptions in this directory (tenant)** option to sync all resources in your directory. Otherwise, specify the Azure subscription ID - The unique ID for the subscription that you want to sync. This can be found in the Azure portal if you go to _Subscriptions_ and select the subscription. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ## Step 3: Choose how to configure the Entra ID integration The Entra ID integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the Entra ID integration to sync data After you add your Entra ID credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the Entra ID integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Entra ID-only assets are created. 1. Activate a [connection to Entra ID](https://console.runzero.com/ingest/azuread). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure it has access to the organization you are currently in. 3. Optionally provide a filter following the [Microsoft Graph API filter syntax](https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http). We will only import devices that match the filter. 4. Enter a name for the task, like `Entra ID sync`. 5. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 6. Under **Task configuration**, choose the site you want to add your assets to. 7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 8. If you want to include assets in your integration import that the Entra ID account has marked as inactive, switch the **Include inactive assets** toggle to _Yes_. By default, the integration will not include assets that are marked as inactive. 9. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Entra ID integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the **Azure AD** toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the **Azure AD** toggle for the credential you wish to use to _Yes_. 5. Click _Initialize scan_ to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View Entra ID assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Entra ID assets. These assets will have an Active Directory icon listed in the _Source_ column. To filter by Entra ID assets, consider running the following queries: * [View all Entra ID assets](https://console.runzero.com/inventory?search=source%3Aazuread): ``` source:azuread ``` * [View runZero assets not connected to Entra ID](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Aazuread): ``` source:runzero AND NOT source:azuread ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by Entra ID.

The Entra ID integration provides details about users and groups in addition to enriching asset inventory data. Go to Inventory > Users or Inventory > Groups to view the data provided by Entra ID.

## Filtering Entra ID assets {#azure-ad-filtering} An optional filter can be applied to Entra ID integration tasks. runZero uses Microsoft Graph `$filter` query paramater to filter assets. GraphQL follows the syntax ` [operator] `. Multiple expressions can be combined for more complex filtering by adding an `and` or `or` between expressions. ### Properties {#azure-ad-filtering-properties} Any property that runZero imports from Entra ID can be used to apply a filter. The following are some examples. | Entra ID Property | runZero Attribute | Description | Example | | ------------------------ | ----------------------------------- | -------------------------------------------------- | ------------------- | | `displayName` | @azuread.dev.displayName | The hostname of the device | EXPLORER-01 | | `operatingSystem` | @azuread.dev.operatingSystem | The operation system of the device | Windows | | `operatingSystemVersion` | @azuread.dev.operatingSystemVersion | The version of the specified operoating system | 10.0.x | | `manufacturer` | @azuread.dev.manufacturer | The manufacturer of the device | Dell Inc. | | `model` | @azuread.dev.model | The model of the device | Precision 3560 | | `isManaged` | @azuread.dev.isManaged | Boolean value specifying whether device is managed | true, false | | `managementType` | @azuread.dev.managementType | Description of how the device is managed | MDM, MicrosoftSense | | `deviceOwnership` | @azuread.dev.deviceOwnership | Description of who owns the device | Company, Personal | ### Operators {#azure-ad-filtering-operators} The following are common operators that can be used in an Entra ID filter. - Equal to (`eq`) - Not equal to (`ne`) - Has (`has`) - Less than (`lt`) - Greather than (`gt`) - Less than or equal to (`le`) - Greater than or equal to (`ge`) The following are common functions that can be used in an Entra ID filter. Functions follow the syntax `function(, )`. - Starts with (`startswith`) - Ends with (`endswith`) ### Example Filters {#azure-ad-filtering-examples} The following are examples of filters that can be applied to an Entra ID integration. | Search Filter | Description | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------| | `not(startsWith(operatingSystem, 'Android'))` | Import all assets except those with an Android operating system | | `not(operatingSystem eq 'iOS') and not(operatingSystem eq 'iPad')` | Import all assets execpt those with an iOS or IPad operating system | | `startswith(displayName, 'PROD')` | Import all devices with a hostname that starts with PROD | | `not(startswith(displayName, 'DEV'))` | Import all devices except those with a hostname that starts with DEV | | `deviceOwnership eq 'Company' or isManaged eq true` | Import all devices that are owned by company or that are configured as managed devices | For more information about filter syntax and additional examples, check [Microsoft's Graph API documentation](https://learn.microsoft.com/en-us/graph/filter-query-parameter). ## Troubleshooting {#azure-ad-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Azure Active Directory integration unable to connect? 1. Are you getting any data from the Entra ID integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Entra ID integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue ### How do I solve the following Entra ID errors? * `(invalid_client) AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'` 1. This error can be corrected by enabling **Allow Public Client Flows** in Entra ID. This can be accomplished by entering the Application details page under _Authentication > Advanced Settings_. From here you can toggle the **Allow Public Client Flows** setting to _Yes_. 2. It can also be helpful to ensure that application permissions were granted correctly when registering the Azure application for Entra ID API access. To do this, navigate to the API permissions settings page and ensure that each of the API/Permissions have the _type_ set to _application_. Also make sure that the permission granted is _Grant Admin Consent for Default Directory_. * `failed to get Entra ID groups: invalid response: 403 (403 Forbidden)` This error is likely due to an issue with credentials. Please review the documentation and check your credentials to ensure everything was entered correctly and no steps were accidentally skipped. --- docs/microsoft-intune.md --- title: Microsoft Intune --- runZero integrates with ((Microsoft Intune)) to allow you to sync and enrich your asset inventory. Adding your Microsoft Intune data to runZero makes it easier to find unmanaged assets on your network. Data added includes the [discovered apps](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps#details-of-discovered-apps) from Intune. Managed apps (those pushed to devices by Intune) are not currently reported. ## Getting started {#intune-getting-started} To set up the Microsoft Intune integration, you'll need to: 1. Configure Microsoft Intune to allow API access from runZero. 2. Add the Microsoft Intune credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Microsoft Intune integration to sync your data with runZero. ## Requirements {#intune-requirements} Before you can set up the Microsoft Intune integration: * Make sure you have access to the Microsoft Azure portal. ## Step 1: Register an Azure application for Microsoft Intune API access {#intune-api-access} runZero can authenticate to the Microsoft Intune API using either a username and password or a client secret. Register an application to configure Microsoft Intune API access. 1. Sign in to the Microsoft Azure portal. 2. Go to _App registrations_ and click on _+ New registration_. * Provide a name. * Select the supported account types. * Optionally add a redirect URI. 3. Click _Register_ to register the application. 4. Once the application is created, go back to the main Azure portal page and select _App registrations_. You should be able to find the application you just registered. (It may help to select the _Owned applications_ tab.) Click on the app's name 5. You should see an overview of the app registration. Note the following information: * Application (client) ID * Directory (tenant) ID 6. From the application's details page, go to _Manage > API permissions_ and choose _+ Add a permission_. 7. Select _Microsoft Graph_ from the list of Microsoft APIs. 8. Select the correct permissions type for your needs: * **Username & password**: select _Delegated permissions_ * **Client secret**: select _Application permissions_ 9. Search for and select the following required permission: * `DeviceManagementManagedDevices.Read.All` * `User.Read.All` * `DeviceLocalCredential.ReadBasic.All` (only required if you choose to enable the Include LAPS Information option within the integration) 10. Click _Add permissions_ to save the permissions to the application. 11. Click _Grant admin consent_ to grant consent for the permissions to the application. 12. If using a client secret, also perform the following steps from the app management pages: * Navigate to _App registrations_ and select the application you created. * Go to _Certificates & secrets_ and click on _+ New client secret_. * Enter a description. * Select the expiration. * Click _Add_ to create the client secret and save the client secret value. ## Step 2: Add the Microsoft Intune credential to runZero {#intune-credential} Adding the Microsoft Intune credential requires adding an Azure username and password or an Azure Client Secret to runZero. The following sub-steps break down each task. ### Step 2a: Add an Azure Username & Password credential to runZero {#intune-credential-userpass} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_. 2. Provide a name for the credential, like `Azure User/Pass`. 3. Choose _Azure Username & Password_ from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure username** - The username for your Azure cloud account. This cannot be a federated user account. * **Azure password** - The password for your Azure cloud account. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ### Step 2b: Add an Azure Client Secret credential to runZero {#intune-credential-clientsecret} This type of credential can be used to sync all resources in a single directory (across multiple subscriptions). 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_. 2. Provide a name for the credential, like `Azure Client Secret`. 3. Choose _Azure Client Secret_ from the list of credential types. 4. Provide the following information: * **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application. * **Azure client secret** - To generate a client secret, go to _App registrations_, select your application, go to _Manage > Certificates & secrets_ and click on _New client secret_. * **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application. 5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure. ## Step 3: Choose how to configure the Microsoft Intune integration The Microsoft Intune integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independent of a scan, from either the cloud or one of your Explorers, and only performing the integration sync. ## Step 4: Set up and activate the Microsoft Intune integration to sync data After you add your Microsoft Intune credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the Microsoft Intune integration as a connector task A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Microsoft Intune-only assets are created. 1. Activate a [connection to Microsoft Intune](https://console.runzero.com/ingest/intune). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure it has access to the organization you are currently in. 3. Optionally provide a filter to import only devices that match it. You can find more details in the [Filtering Intune assets](#intune-filtering) section below. 4. If you wish to retrieve LAPS information from Intune, enable the Include LAPS Information option. This functionality also has additional permission requirements; please see the [Intune API Access](#intune-api-access) section above. Please note that **runZero does not collect passwords from LAPS when using this option.** 5. Enter a name for the task, like `Microsoft Intune sync`. 6. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 7. Under **Task configuration**, choose the site you want to add your assets to. 8. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 9. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Microsoft Intune integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the Intune toggle to `Yes`, and change any of the default options if needed. 4. On the Credentials tab, set the Intune toggle for the credential you wish to use to `Yes`. 5. Click _Initialize scan_ to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View Microsoft Intune assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Microsoft Intune assets. These assets will have an Active Directory icon listed in the _Source_ column. To filter by Microsoft Intune assets, consider running the following queries: * [View all Microsoft Intune assets](https://console.runzero.com/inventory?search=source%3Aintune): ``` source:intune ``` * [View runZero assets not connected to Microsoft Intune](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Aintune): ``` source:runzero AND NOT source:intune ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by Microsoft Intune. ## Filtering Intune assets {#intune-filtering} An optional filter can be applied to Intune integration tasks. runZero uses the Intune reports API to retrieve assets from the `DevicesWithInventory` report. This API accepts a filter field to narrow down the results. ### Properties {#intune-filtering-properties} The `DevicesWithInventory` report supports filtering based on the following properties: - CreatedDate - LastContact - CategoryName - CompliantState - ManagementAgents - OwnerType - ManagementState - DeviceType - JailBroken - EnrollmentType - PartnerFeaturesBitmask For the most up-to-date list of properties, please refer to Microsoft's documentation on the [DevicesWithInventory](https://learn.microsoft.com/en-us/mem/intune/fundamentals/reports-export-graph-available-reports#deviceswithinventory) report. Note that not all the properties listed on that table are filterable. Scroll just below the table to find a separate list of properties that can be used in filters. ### Operators {#intune-filtering-operators} There is no official documentation on the filter syntax or supported operators for the Intune reports API, but based on our testing, the following operators may be supported. In practice, we've found that some of these, such as `not` and `in`, can produce errors, so your results may vary. - Equal to (`eq`) - Not equal to (`ne`) - Logical negation (`not`) - In (`in`) - Has (`has`) - Less than (`lt`) - Greater than (`gt`) - Less than or equal to (`le`) - Greater than or equal to (`ge`) The syntax appears to be similar to the `$filter` query parameter used elsewhere in Microsoft Graph. Examples for this syntax can be found in [Use the $filter query parameter](https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http). We recommend testing filters carefully and starting with basic operators like `eq` and `ne` for best results. ### Example Filters {#intune-filtering-examples} The following are examples of filters that can be applied to an Intune integration. | Search Filter | Description | | --------------------------------------------------------------------- | ---------------------------------------------------------------------| | `DeviceType eq 'android'` | Import all android devices | | `LastContact ge '2023-02-23 23:50:01.0000000'` | Import devices that checked in after a specific date and time | ## Troubleshooting {#intune-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Microsoft Intune integration unable to connect? 1. Are you getting any data from the Microsoft Intune integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Microsoft Intune integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue ### How do I solve the following Microsoft Intune error: * `(invalid_client) AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'` This error means that you need to enable `Public Client Flows` in Azure. To do so, follow these steps: 1. Navigate to the App Registration page in the Azure portal 2. Choose _Authentication_ from the left navigation 3. Select _Advanced Settings_ 4. Toggle the _Allow Public Client Flows_ switch at the bottom of the page to _Yes_ --- docs/miradore.md --- title: Miradore MDM aliases: ["/docs/set-up-miradore/"] --- runZero integrates with ((Miradore)) mobile device management (MDM) to deliver greater visibility into your mobile assets. This integration imports data from the [Miradore API](https://www.miradore.com/knowledge/integrations/miradore-api/) to enrich your asset inventory. Syncing with Miradore allows you to view information about device hardware, OS version, associated user, and more. This integration imports all enrolled devices. ## Getting started {#miradore-getting-started} To set up the Miradore integration, you'll need to: 1. Sign in to your Miradore web portal and create a new API key. 2. Add the Miradore credential to runZero, which includes the endpoint hostname and API key. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Miradore integration to sync your data with runZero. ## Requirements {#miradore-requirements} Before you can set up the Miradore integration: * Make sure you have access to the Miradore MDM portal as an administrator. ## Step 1: Create a Miradore API key 1. Sign in to your Miradore portal as an administrator. 2. Click on the **System > Infrastructure diagram** link from the left-side navigation. 3. Scroll down to the find the **API** node in the diagram. Click this and choose **Create API key**. 3. Give this new key a name and copy the secret value. ## Step 2: Add the Miradore credential to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click **Add Credential**. 2. Provide a name for the credential, like `Miradore MDM`. 3. Choose **Miradore MDM API Key** from the list of credential types. 4. Provide the following information: * **Name** - Give this credential a unique name (ex: Miradore) * **Miradore endpoint hostname** - The URL for your Miradore portal. * **Miradore API key** - The API key created in step 1. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Miradore. ## Step 3: Choose how to configure the Miradore integration The Miradore integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the Miradore MDM integration to sync data After you add your Miradore credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the Miradore integration as a connector task A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Miradore-only assets are created. 1. Activate a [connection to Miradore](https://console.runzero.com/ingest/miradore). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. Enter a name for the task, like `Miradore sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**, choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 7. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Miradore integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the Miradore toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the Miradore toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View Miradore assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Miradore assets. These assets will have a Miradore icon listed in the **Source** column. To filter by Miradore assets, consider running the following queries: * [View all Miradore assets](https://console.runzero.com/inventory?search=source%3Amiradore): ``` source:miradore ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by the Miradore API. ## Troubleshooting {#miradore-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Miradore integration unable to connect? 1. Are you getting any data from the Miradore integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Miradore integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Miradore host if it is on-premises. --- docs/netbox.md --- title: NetBox CMDB --- runZero integrates with ((NetBox)) configuration management database (CMDB) using the [NetBox REST API](https://demo.netbox.dev/api/schema/swagger-ui/) to enrich your asset inventory. ## NetBox limitations {#netbox-limitations} runZero explicitly supports NetBox version 4. Older versions (3.x) may be compatible, but are not specifically tested or supported. Since NetBox data entry is free-form, the runZero integration may not be a good fit for your organization, and we strongly recommend testing this integration in a Project first before configuring it for a production Organization. The NetBox integration will import Devices and Virtual Machines, as well as their associated resources. The NetBox integration will NOT create entities for anything other than Devices and Virtual Machines. The Device and Virtual Machine records are imported as runZero assets with the following fields: * Device or Virtual Machine * ID in the form of `device.` or `vm.` * Name * FirstSeenTS and LastSeenTS * Serial * AssetTag (Device only) * Interfaces * IP addresses for PrimaryIP / PrimaryIP4 / Primary IP6 / OOB IP * Additional IP addresses using the `ip.field` syntax * NAT Inside and NAT Outside addresses * MAC Addresses (if entered in NetBox) * CreatedTS and UpdatedTS * ID, DNSName, Name, Comments, and Description * Module Name, MTU, Speed (Device only) * Tagged and Untagged VLANs * Custom Fields * Prefixes * VLAN and CIDR * ID, Comments, and Description * Role Name * Custom Fields * Location * ID and Name * Latitude and Longitude * Chained Location Path * Custom Fields * Rack * ID and Name * Position and Rack Face * Status * Manufacturer * ID, Name, and Model * Comments, Description, and Part Number * Custom Fields * Device Role * ID, Name, Description * Custom Fields * Platform * ID & Name * Custom Fields * Site * ID, Name, Description, Comments * Facility, Physical Address, Shipping Address * Region, Group * Custom Fields * Virtual Chassis * ID, Name, Comments, and Description * Master ID and Master Name * VC Position and Priority * Interface Count * Inventory Item Count * Custom Fields The following top-level attributes are rollups across all sub-fields: * Addrs * Names * MACs * VLANs ## NetBox asset matching {#netbox-asset-matching} runZero will use the Name, IP Address, and MAC Addresses to match NetBox Devices and Virtual Machines to runZero assets. If there isn't a direct match, runZero will create a new asset record, unless the "Exclude assets that cannot be merged into an existing asset" option is enabled. Since NetBox data is typically static and network assets tend to change over time, there is a good chance that many assets will not match. MAC Addresses are the most reliable way to correlate these, but many organizations do not fill out the MAC Address fields in NetBox. ## NetBox asset fingerprinting {#netbox-asset-fingerprinting} runZero will use the `mfg.name` as the hardware vendor and `mfg.model` as the hardware model for Devices. runZero will report Virtual Machine vendors by matching the Cluster Type field to a known list of common hypervisors (Xen, VMware, Proxmox, etc.). The `platform.name` field, with and without the `mfg.name` field as a prefix will be used to find an operating system match. The NetBox operating system data in `platform.name` will be treated as low-confidence relative to agent-based sources like EDRs and CMDB. The NetBox hardware values will be treated similarly, with live agent-based sources taking priority. ## NetBox-to-runZero custom field mapping {#netbox-custom-fields} The NetBox integration allows for users to map custom fields within NetBox to attributes within runZero. These mappings will override the `mfg.name`, `mfg.model`, and `platform.name` attributes as noted above. Please note that in the field mapping widget within the NetBox task configuration, the "NetBox field" inputs must be the **name** properties of the custom fields within NetBox. The following runZero attributes are supported for custom field mapping: * `hostnames`: The hostnames to apply to the asset within runZero. Multiple hostnames within the NetBox custom field must be comma-separated and no hostname may contain tab characters. This custom field must be a `Text` type. * `manufacturer`: The manufacturer to apply to the asset within runZero. This custom field must be a `Text` type. * `model`: The model to apply to the asset within runZero. This custom field must be a `Text` type. * `device_type`: The type of device to apply to the asset within runZero. This custom field must be a `Text` type. * `first_seen_ts`: The "first seen time" to apply to the asset within runZero. This custom field must be either a `Date & time` or `Date` type. * `os`: The type of operating system to apply to the asset within runZero. This custom field must be a `Text` type. * `os_version`: The version of the operating system to apply to the asset within runZero. This custom field must be a `Text` type. ### Usage within the runZero CLI scanner {#netbox-custom-fields-cli} To use the custom field mapping functionality within the runZero CLI scanner, provide a JSON array with the following example structure as an argument, where in each array item the "key" represents the NetBox custom field name and the "value" represents the runZero attribute: ```shell --netbox-field-mappings '[{"key":"netboxHostnames","value":"hostnames"},{"key":"netboxManufacturer","value":"manufacturer"}]' ``` In this example, `netboxHostnames` is the NetBox custom field being mapped to the runZero `hostnames` attribute and `netboxManufacturer` is the NetBox custom field being mapped to the runZero `manufacturer` attribute. ## Searchable time attributes The NetBox integration will process all `Date & time` or `Date` NetBox attributes and create searchable attributes from them within runZero. For example, a NetBox attribute called "lastChecked" with a value of `2024-07-26T15:30:00Z` will have a new attribute created from it called `lastCheckedTS` with a Unix epoch timestamp value of `1722017400`. ## Getting started {#netbox-started} To set up the NetBox integration, you will need: 1. A NetBox instance in the cloud or that is reachable by one of your runZero Explorers. 2. An administrative account in the NetBox instance. 3. A v1 NetBox API key (we do not currently support v2 API keys, which can be identified by their prefix of `nbt_`). ## Step 1: Create a NetBox API key 1. Sign in to your NetBox portal. 2. Click on your name in the upper right and select **API Tokens** from the drop-down. 3. Click **Add a Token** and define a new token with no expiration and without Write permissions. 3. Give this new key a name and copy the secret value. ## Step 2: Add the NetBox credential to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click **Add Credential**. 2. Provide a name for the credential, like `NetBox CMDB`. 3. Choose **NetBox API Key** from the list of credential types. 4. Provide the following information: * **Name** - Give this credential a unique name (ex:NetBox) * **NetBox URL** - The URL for your NetBox portal. * **NetBox API key** - The API key created in step 1. * **Insecure** - Set this to `Yes` if you want to attempt authentication without a verified thumbprint. * **NetBox thumbprints** (optional) - A set of `IP=SHA256:B64HASH` or `domain.tld=SHA256:B64HASH` pairs to trust for authentication. * You may scan your NetBox instance with runZero in order to obtain the TLS thumbprint. The [TLS fingerprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=tls.fp.sha256&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20[tls.fp.sha256]) lists all previously seen fingerprints. * If _insecure_ is set to _No_ and no thumbprints are provided: * With a self-signed certificate, the connection will fail because the certificate chain cannot be verified. * With a valid certificate from a public CA, the connection can work without thumbprints. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from NetBox. ### Step 3: Configure the NetBox integration as a connector task A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new NetBox-only assets are created. 1. We strongly recommend testing NetBox in a new Project first before applying this to your production Organization. Create a new Project. 2. Activate a [connection to NetBox](https://console.runzero.com/ingest/netbox). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 3. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization or project you are currently in. 4. Enter a name for the task, like `NetBox sync`. 5. Leave the default settings to create a one-off sync task. 6. Under **Task configuration**, choose the site you want to add your assets to. NetBox assets that do not match existing assets will use this site by default. 7. If you want to exclude assets that have not been scanned by runZero from your integration import, tick the **Exclude assets that cannot be merged into an existing asset** checkbox. 8. Activate the connection when you are done. The task will run. You can always check the [Tasks](https://console.runzero.com/tasks) page to track the status. ## Step 4: View NetBox assets After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your NetBox assets. These assets will have a NetBox icon listed in the **Source** column. To filter by NetBox assets, consider running the following queries: * [View all NetBox assets](https://console.runzero.com/inventory?search=source%3Anetbox): ``` source:netbox ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by the NetBox API. Review the new NetBox assets and confirm that the NetBox-sourced asset count is roughly in-line with your overall inventory and the total in NetBox itself. If there are far fewer NetBox-sourced assets in runZero, you may want to avoid the final step until NetBox is updated with better correlation data. ## Step 5: Enable Unknown Assets in Recurring Sync Configure a new recurring NetBox task, with **Exclude assets that cannot be merged into an existing asset** disabled. This will create new assets for anything in NetBox that runZero can't correlate to in your asset inventory. If this process creates significant duplicates, delete all assets matching the filter `source_count:1 AND source:netbox`, and re-enable the _Exclude unknown assets_ option in your recurring task until the NetBox records have better correlation data (MAC addresses, hostnames, etc.). ## Troubleshooting {#netbox-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the NetBox integration unable to connect? 1. Are you getting any data from the NetBox integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the NetBox integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the URL * 404 - hitting an unknown URL on the server * 401 - not authorized, likely a credential issue * 403 - access denied, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the NetBox host if it is on-premises. ### Why aren't my custom field mappings aren't working properly? 1. Ensure you are using the `name` of the custom field and **not** the `label`. 2. Ensure the custom fields are applied to the correct types. The NetBox integration only supports the "Device" and "Virtual Machine" types within NetBox. 3. If your hostnames are becoming malformed within runZero, ensure they are comma-separated if there are multiple hostnames within the custom field. Additionally, ensure there are no tab characters present within the custom field. 4. All of the custom fields except for the `first_seen_ts` attribute must be the `Text` type within NetBox. `first_seen_ts` must be either a `Date & time` or `Date` type. --- docs/qualys.md --- title: Qualys VMDR --- runZero integrates with ((Qualys VMDR)) by importing data from the Qualys KnowledgeBase [API](https://www.qualys.com/docs/qualys-api-vmpc-user-guide.pdf). ## Asset inventory {#qualys-asset-inventory} There is a column on the asset inventory page showing the count of vulnerabilities detected by Qualys for each asset. When a single asset is selected, the vulnerabilities table lists all the results related to that asset. The vulnerability count can be impacted by the type of vulnerability scan as well as the import settings selected. ## Vulnerabilities table {#qualys-vulnerabilities-table} The **Vulnerabilities** tab of the inventory lists all vulnerability results that have been imported from Qualys. The table lists every result, and selecting a result will take you to the page for the impacted asset. ## Severity and risk scores {#qualys-scoring} Qualys assigns all vulnerabilities a severity rating (Minimal, Medium, Serious, Critical, Urgent). runZero normalizes the severities shown in the vulnerability inventory to be consistent across the runZero Console. | runZero Severity | Qualys Severity | | ---------------- | --------------- | | Info | 1 / Minimal | | Low | 2 / Medium | | Medium | 3 / Serious | | High | 4 / Critical | | Critical | 5 / Urgent | runZero will also normalize risk scores assigned by Qualys. A risk score of 0.0 will be shown as `none` in the runZero Console, and all other risk scores will match the assigned severity level. ## Getting started with Qualys {#qualys-getting-started} To set up the Qualys VMDR integration, you'll need to: 1. Create or obtain user credentials with access to the Qualys API. 2. Configure [CVSS scoring in Qualys](https://qualysguard.qualys.com/qwebhelp/fo_portal/setup/cvss_scoring.htm). 2. Add the Qualys API username, password, and account API URL in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the Qualys integration to pull your data into runZero. ## Requirements {#qualys-requirements} Before you can set up the Qualys VMDR integration: * Make sure you have access to the Qualys Cloud Platform portal. ### Step 1: Add the Qualys credentials to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Qualys`. 2. Choose **Qualys Username & Password** from the list of credential types. 3. Provide the following information: * **Qualys username** - the username you want to use to connect to the Qualys API. * **Qualys password** - the password for your Qualys API username. * **Qualys account API URL** - the URL of the Qualys API for the relevant account. The expected format is `https://ip:port` or `https://domain.tld:port`. This URL is unique for [each Qualys user](https://www.qualys.com/platform-identification/). 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Qualys VMDR.
Note
The role of the Qualys API user will determine which VM scanned hosts are visible to the integration. Managers may view all VM scanned hosts in the subscription. Auditors have no permission to view VM scanned hosts. Unit Managers may view VM scanned hosts in the user's assigned business unit. Scanners and Readers may view VM scanned hosts in the user's account, but must be assigned to the assets through asset groups in VM/VMDR.
## Step 2: Choose how to configure the Qualys integration The Qualys integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 3: Set up and activate the Qualys integration to sync data After you add your Qualys credential, you'll need to sync your data.
Note
The Qualys Cloud Platform enforces limits on the API calls subscription users can make. Both API controls are limited per subscription based on your service level. The tasks generated by this integration may experience slow performance or failures as a result of the enforced API limits. The Qualys API documentation on this topic can be found here.
### Step 3a: Configure the Qualys scan probe You can run the Qualys VMDR integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. In a new or existing scan configuration: * Ensure that the _QUALYS_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct Qualys credential to _Yes_ in the _Credentials_ tab. * Optionally, set the [severity and risk levels](#qualys-scoring) for ingested vulnerability scan results. ### Step 3b: Configure the Qualys connector A connector requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Qualys-only assets are created. 1. Activate a [connection to Qualys](https://console.runzero.com/ingest/qualys). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Set the [severity and risk levels](#qualys-scoring) you want to import (optional). 1. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 1. Specify the tags to include in the import. This should be a comma-separated list. Only assets that match any of the provided tags will be imported (optional). 1. Specify the network IDs to include in the import. This should be a comma-separated list. Only assets that match any of the provided network IDs will be imported (optional). 1. Enter a name for the task, like `Qualys sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. Enter a description for the task (optional). 1. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 1. If you want to include assets that have not been assessed for vulnerabilities, switch the **Include unscanned assets** toggle to _Yes_. 1. Enter a number of hours in the `Last update filter` to exclude assets that have not been scanned in longer than that time (optional). Leaving the value blank will use the default of 30 days. 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ## Step 4: View Qualys assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Qualys assets. These assets will have a Qualys icon listed in the **Source** column. The Qualys integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Qualys VMDR. To filter by Qualys assets, consider running the following query: * [View all Qualys assets](https://console.runzero.com/inventory?search=source%3AQualys): ``` source:Qualys ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Qualys VMDR scan data. ## Troubleshooting {#qualys-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Qualys integration unable to connect? 1. Are you getting any data from the Qualys integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Qualys integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Qualys host if it is on-premises. --- docs/palo-alto.md --- title: Palo Alto Networks Firewall --- runZero integrates with Palo Alto Networks Firewall using the [PAN-OS XML API](https://docs.paloaltonetworks.com/ngfw/api/api-authentication-and-security/pan-os-api-authentication) to provide additional network visibility, enhance network context, and improve [reporting](https://help.runzero.com/docs/switch-topology-report/). ## Getting started {#panos-getting-started} To set up the Palo Alto Networks Firewall integration, you'll need to: * Create or obtain API Keys to use with the Palo Alto Networks Firewall XML API. * Add the Palo Alto Networks Firewall API key in runZero. * Perform Palo Alto Networks Firewall synchronization ## Requirements {#panos-requirements} * Before you can set up the Palo Alto Networks Firewall integration, make sure you have an API Key for your PAN OS XML. * Prior to adding a Palo Alto Networks Firewall credential, scan your Palo Alto Networks Firewall with a runZero Explorer if you want to use trusted authentication (optional). ## Step 1: Add the Palo Alto Networks Firewall credential to runZero {#step-1-add-the-panos-credential-to-runzero} 1. Go to the [Add credential](https://console.runzero.com/credentials/new) page in runZero. Provide a name for the credentials, like **PAN-OS Firewall**. 2. Choose **Palo Alto Networks Firewall API Key** from the list of credential types. 3. Provide the following information: * **Palo Alto Networks API key** - The API key you want to use with the Palo Alto Networks Firewall integration. Ensure the XML API is enabled by following the steps in this guide: [https://docs.paloaltonetworks.com/ngfw/api/api-authentication-and-security/pan-os-api-authentication](https://docs.paloaltonetworks.com/ngfw/api/api-authentication-and-security/pan-os-api-authentication). Once the XML API is enabled, you can generate the API key by following the steps in this guide: [https://docs.paloaltonetworks.com/ngfw/api/api-authentication-and-security/generate-api-key](https://docs.paloaltonetworks.com/ngfw/api/api-authentication-and-security/generate-api-key) * **Palo Alto Networks insecure** - Set this to `Yes` if you want to attempt authentication without a verified thumbprint. * **Palo Alto Networks thumbprints** (optional) - A set of `IP[:port]=SHA256:B64HASH` or `hostname.domain.tld=SHA256:B64HASH` pairs to trust for authentication. * You will need to scan your Palo Alto Networks firewalls with runZero in order to obtain the TLS thumbprint. The [PAN API thumbprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=pan.api.thumbprint&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20%5Bpan.api.thumbprint%5D) lists all previously seen thumbprints. * **CIDR allow list** - Set which IP addresses this API Key will be sent to in the **CIDR allow list**. 4. If you want all other organizations to be able to use this credential, select the Make this a global credential option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Palo Alto Networks Firewall. ## Step 2: Performing Palo Alto Network synchronization {#step-2-performing-panos-synchronization} Once you have defined your Palo Alto Networks Firewall API key credentials, the second step is to enable Palo Alto Networks Firewall synchronization as part of a scan task. Any task which includes scanning the Palo Alto Networks Firewalls can be used to synchronize PAN-OS data. On the Credentials tab of the scan setup, use the toggle switch to enable the appropriate set of Palo Alto Networks credentials. When the scan runs, the Explorer will use the credentials to authenticate with any Palo Alto Networks Firewall it finds that the credentials are configured to trust. Data discovered about Palo Alto Networks Firewalls will be imported into runZero automatically, and merged with the other information runZero finds by scanning. ## Step 3: View Palo Alto Networks Firewall assets {#step-3-view-panos-assets} To filter by Palo Alto Networks Firewall assets, consider running the following queries: [View all Palo Alto Networks Firewall assets:](https://console.runzero.com/inventory?search=attribute%3Apan.api.thumbprint) ``` attribute:pan.api.thumbprint ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by Palo Alto Networks. --- docs/prisma.md --- title: Palo Alto Prisma Cloud --- runZero integrates with Palo Alto ((Prisma Cloud)) by importing data from the [Prisma API](https://pan.dev/prisma-cloud/api/). This integration allows you to sync data about your cloud assets and vulnerabilities from Prisma to provide better visibility of your cloud assets and security posture. The supported Prisma cloud sources are AWS, Azure, and GCP. ## Getting started with Prisma {#prisma-getting-started} To set up an integration with Prisma, you'll need to: 1. Create a Palo Alto Prisma Cloud credential in runZero. 2. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 3. Activate the integration to pull your data into runZero. ## Step 1: Obtain your Prisma API credentials {#Prisma-step1} 1. Follow the [Prisma documentation](https://pan.dev/prisma-cloud/api/cspm/#cloud-security-user-roles) to create a Prisma cloud user role with sufficient permissions. See [user role descriptions](https://docs.prismacloud.io/en/enterprise-edition/content-collections/administration/prisma-cloud-administrator-roles) for more information. 2. Obtain your Prisma Cloud API access key and secret key. These will be used to authenticate against the Prisma Cloud API. Follow the [Prisma documentation](https://pan.dev/prisma-cloud/api/cspm/#cloud-security-api-authorization) to configure them properly. 3. Identify your API URL. This will be sent to you from Palo Alto in your fulfillment email. See [possible URL values](https://pan.dev/prisma-cloud/api/cspm/api-urls/). ## Step 2: Add the Prisma credential to runZero {#Prisma-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Palo Alto Networks Prisma Cloud`. 2. Choose **Prisma Client Secret** from the list of credential types. 3. Create your Prisma service account via the settings page in the Prisma portal, and then provide the following information: * **Prisma Cloud Access Key** - The access key you obtained from the steps above. * **Prisma Cloud Secret Key** - The secret key you obtained from the steps above. * **Prisma API URL** - The API Endpoint URL used to access the Prisma API. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Prisma Cloud. ## Step 3: Choose how to configure the Prisma integration {#Prisma-step3} The Prisma integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#Prisma-step4} After you add your Prisma credential, you'll need to sync your data from Prisma. ### Step 4a: Configure the Prisma integration as a connector task {#Prisma-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Prisma-only assets are created. 1. Activate a connection to [Prisma](https://console.runzero.com/ingest/Prisma). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Set the **Exclude importing vulnerabilities** toggle if you want vulnerability records to be saved or not. 4. Set the **Exclude importing software** toggle if you want software records to be saved or not. 5. Set the **Exclude assets that can not be merged into an existing asset** toggle if you want no new asset records created, only enrich existing assets. 6. Set the severity and risk levels you want to import. 7. Enter a name for the task, like `Prisma Sync` (optional). 8. In the Run task with section, choose the Explorer or Explorer Group to perform this connector task from (optional). 9. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 10. Enter a description for the task (optional). 11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Prisma integration as a scan probe {#Prisma-step4b} You can run the Prisma integration as a scan probe so that the runZero Explorer will pull your Prisma assets into the runZero Console. In a new or existing scan configuration: * Ensure that the _Prisma_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Optionally, set the severity and risk levels for ingested vulnerability results. * Set the correct _Prisma_ credential to _Yes_ in the _Credentials_ tab. ### Step 5: View Prisma assets, and vulnerabilities {#Prisma-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Prisma assets. These assets will have a Prisma icon listed in the **Source** column. The Prisma integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to **Inventory** > [**Vulnerabilities**](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Prisma. To filter by Prisma assets, consider running the following queries: * [View all Prisma assets](https://console.runzero.com/inventory?search=source%3APrisma): ``` source:Prisma ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from Prisma Cloud. ## Troubleshooting {#Prisma-troubleshooting} If you see authentication or access errors when running the integration, it is likely that the API URL set for your credential is incorrect. Refer to the fulfillment email you received from Palo Alto. This will contain the correct API URL to use. --- docs/rapid7.md --- title: Rapid7 --- runZero integrates with Rapid7's [((InsightVM))](rapid7-insightvm.md) and [((Nexpose))](rapid7-nexpose.md) to enrich your asset inventory and gain visibility into vulnerabilities detected in your environment. ## Asset inventory {#rapid7-asset-inventory} There is a column on the asset inventory page showing the count of vulnerabilities detected by Rapid7 for each asset. When a single asset is selected, the vulnerabilities table lists all the results related to that asset. The vulnerability count can be impacted by the type of vulnerability scan as well as the import settings selected. ## Vulnerabilities table {#rapid7-vulnerabilities-table} The **Vulnerabilities** tab of the inventory lists all vulnerability results that have been imported from Rapid7. The table lists every result, and selecting a result will take you to the page for the impacted asset. ## Severity and risk scores {#rapid7-scoring} Rapid7 assigns all vulnerabilities a severity rating (Moderate, Severe, or Critical) based on the vulnerability's CVSSv2 score. runZero normalizes the severities shown the vulnerability inventory to be consistent across the runZero Console. | runZero Severity | Rapid7 Severity | CVSS Range | | --------------- | --------------- | -----------| | Info | Moderate | 0.0 | | Medium | Moderate | 0.1 - 3.4 | | High | Severe | 3.5 - 7.4 | | Critical | Critial | 7.5 - 10.0 | runZero will also normalize risk scores assigned by Rapid7. A risk score of 0.0 will be shown as `none` in the runZero Console, and all other risk scores will match the assigned severity level. --- docs/rapid7-insightvm.md --- title: InsightVM --- runZero integrates with ((Rapid7 InsightVM)) by importing data from the [InsightVM API](https://help.rapid7.com/insightvm/en-us/api/index.html). Both Rapid7 InsightVM Cloud and on-premises ((InsightVM)) are supported. For on-premises use you will need to use the InsightVM connector [as a scan probe](#step-2-choose-how-to-configure-the-rapid7-integration) from a runZero Explorer which has network access to the InsightVM deployment. The Insight Platform API is distinct from the InsightVM API, and is not supported. ## Getting started with InsightVM{#insightvm-getting-started} To set up the InsightVM integration, you'll need to: 1. Create or obtain user credentials to use with the InsightVM API. 2. Add the InsightVM API username, password, and API URL in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the InsightVM integration to pull your data into runZero. ## Requirements {#insightvm-requirements} Before you can set up the InsightVM integration: * Obtain credentials for an InsightVM user with administrator access to the InsightVM portal. * Scan your InsightVM with a runZero Explorer if you want to use trusted authentication (optional). ### Step 1: Add the InsightVM credentials to runZero 1. [Create a new credential](https://console.runzero.com/credentials/new) via the runZero [Credentials page](https://console.runzero.com/credentials). 2. Provide a name for the credentials, like `InsightVM`. 3. Choose **InsightVM Username & Password** from the list of credential types. 4. Provide the following information: * **InsightVM username** - The username you want to use to connect to the InsightVM API. This account requires the [`User` role](https://docs.rapid7.com/insightvm/managing-users-and-authentication/#user) or greater permissions in InsightVM. * **InsightVM password** - The password for your InsightVM username. * **InsightVM API URL** - The URL of your InsightVM API instance. By default, the InsightVM API uses port 3780. The expected format is `https://ip:3780` or `https://domain.tld:3780`. RunZero automatically appends `api/3/sites?size=500` to this URL. * **InsightVM insecure** - Set this to `Yes` if you want to attempt authentication without a verified thumbprint. * **InsightVM thumbprints** (optional) - A set of `IP=SHA256:B64HASH` or `domain.tld=SHA256:B64HASH` pairs to trust for authentication. * You will need to scan your InsightVM instance with runZero in order to obtain the TLS thumbprint. The [TLS fingerprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=tls.fp.sha256&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20[tls.fp.sha256]) lists all previously seen fingerprints. * If _InsightVM insecure_ is set to _No_ and no thumbprints are provided: * With a self-signed certificate, the connection will fail because the certificate chain cannot be verified. * With a valid certificate from a public CA, the connection can work without thumbprints. 5. If you want all other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 6. Save the credential. You're now ready to set up and activate the connection to bring in data from InsightVM. ## Step 2: Choose how to configure the Rapid7 integration The Rapid7 InsightVM integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. Scan probes will be the right option for most users. Setting up a connector will only work for if you're self-hosting runZero or your InsightVM instance is publicly accessible. ## Step 3: Sync your InsightVM data After you add your InsightVM credential, you'll need to activate the integration to sync your data. ### Step 3a: Configure the InsightVM scan probe You can run the InsightVM integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. In a new or existing scan configuration: * Ensure that the _INSIGHTVM_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct InsightVM credential to _Yes_ in the _Credentials_ tab. * Optionally, set the [severity and risk levels](docs/rapid7.md/#rapid7-scoring) for ingested vulnerability scan results. * Enter a Site Name Filter to filter results based on the InsightVM site using regular expressions (optional). ### Step 3b: Configure the InsightVM connector A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new InsightVM-only assets are created. 1. Activate a [connection to InsightVM](https://console.runzero.com/ingest/insightvm). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Set the [severity and risk levels](docs/rapid7.md/#rapid7-scoring) you want to import (optional). 4. Input a Site Name Filter to filter your results by specific sites (optional). This input uses regular expressions and supports the [re2 syntax](https://github.com/google/re2/wiki/Syntax). 5. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 6. Enter a name for the task, like `InsightVM sync` (optional). 7. Choose the Explorer to perform this connector task from (optional). 8. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 9. Enter a description for the task (optional). 10. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ## Step 4: View InsightVM assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your InsightVM assets. These assets will have a Rapid7 icon listed in the **Source** column. The InsightVM integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by InsightVM. To filter by Rapid7 assets, consider running the following queries: * [View all Rapid7 assets](https://console.runzero.com/inventory?search=source%3ARapid7): ``` source:Rapid7 ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Rapid7 scan data. ## Troubleshooting {#insightvm-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Rapid7 InsightVM integration unable to connect? 1. Are you getting any data from the Rapid7 InsightVM integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Rapid7 InsightVM integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue ### How can I get a TLS thumbprint for the InsightVM credential? Here is a set of example commands that would calculate your TLS thumbprint, where is the IP address of your InsightVM instance: ```bash $ (echo|openssl s_client -connect :3780 -showcerts 2>/dev/null) | openssl x509 -inform PEM -outform DER | openssl dgst -sha256 -binary | base64 ``` An example value returned by this set of commands would look something like this: `X1NWttnkIQprK6zSre/VweKpbRlj7Dt4M6hNfUacytE=` Use the following entry for the corresponding TLS thumbprint: 192.168.0.3:3780=SHA256:X1NWttnkIQprK6zSre/VweKpbRlj7Dt4M6hNfUacytE= --- docs/rapid7-nexpose.md --- title: Nexpose --- runZero integrates with ((Rapid7 Nexpose)) by importing files that were exported from your ((Nexpose)) instance. ## Getting started with Rapid7 Nexpose {#nexpose-getting-started} To use the Rapid7 Nexpose integration, you'll need to: 1. Download an XML Export or XML Export 2.0 report from Nexpose. 2. Import the Nexpose files through the inventory pages. ## Requirements {#nexpose-requirements} Before you can set up the Nexpose integration: * Make sure you have access to the Nexpose portal. ### Step 1: Export Nexpose vulnerability scan report 1. Sign in to Nexpose with the account being used for the runZero integration. 2. Go to the Reports page and select _Create a report_. 3. From the Export tab, select either XML Report or XML Report 2.0. 4. Set the scan, asset, asset group, or site scope. 5. Click _Save & Run the Report_. 6. When the report completes, save the report to a local file. ### Step 2: Import the Nexpose files into runZero 1. Go to the [Inventory page](https://console.runzero.com/inventory) in runZero. 2. Choose **Import** > **Nexpose XML Export (.xml)** from the list of import types. 3. On the import data page: * Choose the site you want to add your assets to. * Set tags to apply to the imported assets (optional). * Set the [severity and risk levels](docs/rapid7.md/#rapid7-scoring) to ingest (optional). * Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). ### Step 3: View Nexpose assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Nexpose assets. These assets will have a Rapid7 icon listed in the **Source** column. The Nexpose integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Nexpose. To filter by Rapid7 assets, consider running the following queries: * [View all Rapid7 assets](https://console.runzero.com/inventory?search=source%3Atenable): ``` source:Rapid7 ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Nexpose scan file. ## Troubleshooting {#nexpose-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Rapid7 Nexpose integration unable to connect? 1. Are you getting any data from the Rapid7 Nexpose integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Rapid7 Nexpose integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Nexpose host. --- docs/sentinelone.md --- title: SentinelOne --- runZero integrates with ((SentinelOne)) by importing data from the [SentinelOne API](https://www.sentinelone.com/faq/). This integration allows you to sync and enrich your asset inventory, import software installed on assets, and import vulnerabilities affecting the installed software. Adding your SentinelOne data to runZero makes it easier to find things like endpoints that are missing required software or identify vulnerable endpoints.
Any IP address reported by SentinelOne will be treated as a secondary address, not a primary address, since these IPs can be stale and may not be associated with a specific network or site.
## Getting started {#sentinelone-getting-started} To set up the SentinelOne integration, you'll need to: 1. Configure SentinelOne to allow API access through runZero. 2. Add the SentinelOne API key and SentinelOne base API URL in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the SentinelOne integration to sync your data with runZero. ## Requirements {#sentinelone-requirements} Before you can set up the SentinelOne integration: * Make sure you have access to the SentinelOne admin portal. ## Step 1: Configure SentinelOne to allow API access to runZero 1. Sign in to SentinelOne with the account being used for the runZero integration. 2. Go to **User > My User**. 3. **Generate** the API token, then download or copy it. This API key expires and will need to be regenerated every six months. ## Step 2: Add the SentinelOne credential to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `SentinelOne`. 2. Choose **SentinelOne API key** from the list of credential types. 3. Provide the following information: * **SentinelOne API URL** - Your organization-specific base URL, which will depend on your account type. It will be something like `organization.sentinelone.net`. * **SentinelOne API key** - To generate your API key, go to **User > My User** in your SentinelOne portal. From there, a key can be generated, regenerated, or revoked. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from SentinelOne. ## Step 3: Choose how to configure the SentinelOne integration The SentinelOne integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the SentinelOne integration to sync data After you add your SentinelOne credential, you'll need to set up a connector task or scan probe to sync your data. ### Step 4a: Configure the SentinelOne integration as a connector task A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new SentinelOne-only assets are created. 1. Activate a [connection to SentinelOne](https://console.runzero.com/ingest/sentinelone). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Enter a name for the task, like `SentinelOne sync`. 4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 5. Under **Task configuration**, choose the site you want to add your assets to. 6. If you do not want to import software, switch the **Import Software** toggle to _No_. 7. If you do not want to import vulnerabilities, switch the **Import Vulnerabilities** toggle to _No_. 8. If the **Import Vulnerabilities** toggle is set to _Yes_, you can set the desired vulnerability severities to import using the **Severities** checkboxes. 9. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 10. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the SentinelOne integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the SentinelOne toggle to _Yes_, and change any of the default options if needed. 4. On the Credentials tab, set the SentinelOne toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 5: View SentinelOne assets and software After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your SentinelOne assets. These assets will have a SentinelOne icon listed in the **Source** column. The SentinelOne integration gathers details about installed software in addition to enriching asset inventory data. Go to Inventory > [Software](https://console.runzero.com/inventory/software) to view the software data provided by SentinelOne. To filter by SentinelOne assets, consider running the following queries: * [View all SentinelOne assets](https://console.runzero.com/inventory?search=source%3Asentinelone): ``` source:SentinelOne ``` * [Find assets that have a SentinelOne agent installed](https://console.runzero.com/inventory?search=edr.name%3Asentinelone): ``` edr.name:SentinelOne ``` * [Find Windows assets, excluding servers, that are missing a SentinelOne agent](https://console.runzero.com/inventory?search=os%3Awindows%20and%20not%20type%3Aserver%20and%20not%20edr.name%3Asentinelone): ``` os:windows and not type:server and not edr.name:SentinelOne ``` Click into each asset to see its individual attributes. runZero will show you the attributes returned by the SentinelOne API, with the exception of policies. ## Troubleshooting {#sentinelone-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the SentinelOne integration unable to connect? 1. Are you getting any data from the SentinelOne integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the SentinelOne integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the SentinelOne host if it is on-premises. --- docs/shodan.md --- title: Shodan --- runZero integrates with ((Shodan)) by importing data from the [Shodan API](https://developer.shodan.io/api). This integration allows you to sync data about your externally-facing assets and services from Shodan to provide better visibility of your internet footprint and cyber hygiene. ## Getting started {#shodan-getting-started} To set up the Shodan integration, you'll need to: 1. Add the Shodan API key in runZero. 2. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 3. Activate the Shodan integration to sync your data with runZero. ## Requirements {#shodan-requirements} Before you can set up the Shodan integration: * Make sure you have a Shodan account with the correct license to meet your needs. ## Step 1: Add the Shodan credential to runZero 1. Go to the [new credential page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credential, like `Shodan`. 2. Choose **Shodan Search API key** from the list of credential types. 3. Provide your **Shodan Search API key** - To view your API key, go to your Account page in the Shodan portal. Your API key is available on that page and can be reset if needed. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Shodan. ## Step 2: Choose how to configure the Shodan integration The Shodan integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 3: Set up and activate the Shodan integration to sync data After you add your Shodan credential, you'll need to set up a connection or a scan probe to sync your data from Shodan. ### Step 3a: Configure the Shodan integration as a connector task A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Shodan-only assets are created. 1. Activate a [connection to Shodan](https://console.runzero.com/ingest/shodan). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credential you added earlier. If you don't see the credential listed, make sure the credential has access to the organization you are currently in. 3. You can choose whether to specify a Shodan search using Shodan's search syntax, or to have runZero generate a search for all of the public IP addresses of live assets. 4. Enter a name for the task, like `Shodan sync`. 5. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start at the date and time you have set. 6. Under **Task configuration**, choose the site you want to add your assets to. 7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [tasks](https://console.runzero.com/tasks) page to see when the next sync will occur. ### Step 3b: Configure the Shodan integration as a scan probe 1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks). 2. Add or update the scan parameters based on any additional requirements. 3. On the Probes and SNMP tab, choose which additional probes to include, set the Shodan toggle to _Yes_, and change any of the default options if needed. As with running the integration as a connector task, you can choose to specify a Shodan search string directly, or choose _assets_ mode to have runZero generate a search query to look for all public IP addresses of live assets. 4. On the Credentials tab, set the Shodan toggle for the credential you wish to use to _Yes_. 5. Click **Initialize scan** to save the scan task and have it run immediately or at the scheduled time. ## Step 4: View Shodan assets and services After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Shodan assets. These assets will have a Shodan icon listed in the **Source** column. The Shodan integration gathers details about services in addition to enriching asset inventory data. Go to Inventory > [Services](https://console.runzero.com/inventory/services) to view the service data provided by Shodan. To filter by Shodan assets or services, consider running the following queries: * [View all Shodan assets](https://console.runzero.com/inventory?search=source%3Ashodan): ``` source:shodan ``` * [View all Shodan services](https://console.runzero.com/inventory/services?search=source%3Ashodan): ``` source:shodan ``` Click into each asset or service to see its individual attributes. runZero will show you the attributes returned by the Shodan Search API. ## Troubleshooting {#shodan-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Shodan integration unable to connect? 1. Are you getting any data from the Shodan integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Shodan integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/tanium.md --- title: Tanium API Gateway --- runZero integrates with ((Tanium)) by importing data from the [Tanium Gateway API](https://developer.tanium.com/apis/tanium_gateway_schema/queries/endpoints). This integration allows you to sync data about your endpoints, applications, and vulnerabilities from Tanium to provide better visibility over your network. ## Getting started with Tanium {#tanium-getting-started} To set up an integration with Tanium, you'll need to: 1. Generate an API token with the necessary permissions. 1. Configure the Tanium credential in runZero. 1. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 1. Activate the integration to pull your data into runZero. ## Step 1: Generate an API key in Tanium Dashboard {#tanium-step1} 1. Sign in to Tanium and navigate to **Administration > Roles**. 1. Create a role with the necessary permissions: 1. Search for the **Gateway User** role. 1. Select it and click the **Clone** button that appears to create a copy of this role. 1. On the **Clone Role** screen, enable **Platform Content Permissions > Sensor > Read** and add these Content Sets (via the **n+** button beside the green check): * Base * Comply * Comply Reporting * Core AD Query Content * Core Content * Reserved * Tanium Data Service 1. Save the role. 1. Navigate to **Administration > Personas** and click **New Persona** to create a persona using the role you just created: 1. Name the persona. 1. Under **Manage Roles**, search for and apply your new role. 1. Under **Computer Groups**, add the groups you need, or check **Unrestricted Management Rights** to allow access to all Computer Groups. 1. Assign a user or service account which has the permissions granted to the persona. 1. Save the persona. 1. Navigate to **Administration > API Tokens** and click **New API Token**. 1. Enter a name and select a TTL. 1. Select the persona you just created from the dropdown (you may need to refresh the page for it to appear). 1. Enter IP addresses to allow requests from: * If you will run the integration via an Explorer or CLI, enter the IP addresses or ranges of your host(s); * Otherwise, enter `0.0.0.0/0`. 1. Save the API token. ## Step 2: Add the Tanium API token to runZero {#tanium-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. 1. Choose **Tanium API Token** from the list of credential types. 1. Provide a name for the credential, like `Tanium`. 1. Provide the following information: * **Tanium API URL** - Your Tanium API Gateway URL. The full URL will be something like `https://-api.cloud.tanium.com/plugin/products/gateway/graphql`. If the path (`/plugin/products/gateway/graphql`) is omitted, it will be added automatically when the API is called. * **Tanium API token** - The API token (including the `token-` prefix) created in step 1. * **Insecure** - Enable this option to approve authenticating with untrusted endpoints. When enabled, certificate validation is disabled. Use with caution. 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 1. Verify and save the credential. You're now ready to set up and activate the connection to bring in data from Tanium. ## Step 3: Choose how to configure the Tanium integration {#tanium-step3} The Tanium integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#tanium-step4} After you add your Tanium credential, you'll need to sync your data from Tanium. ### Step 4a: Configure the Tanium integration as a connector task {#tanium-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Tanium-only assets are created. 1. Activate a connection to [Tanium](https://console.runzero.com/ingest/tanium). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Optionally provide a list of computer groups to include in the import. The list must be comma-separated. We will only import data for the computer groups specified. 1. Enter a name for the task, like `Tanium Sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. Enter a description for the task (optional). 1. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Tanium integration as a scan probe {#tanium-step4b} You can run the Tanium integration as a scan probe so that the runZero Explorer will pull your Tanium assets into the runZero Console. In a new or existing scan configuration: * Ensure that the _TANIUM_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct _TANIUM_ credential to _Yes_ in the _Credentials_ tab. ## Step 5: View Tanium assets {#tanium-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Tanium assets. These assets will have a Tanium icon listed in the **Source** column. To filter by Tanium assets, consider running the following queries: * [View all Tanium assets](https://console.runzero.com/inventory?search=source%3Atanium): ``` source:Tanium ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from Tanium. --- docs/tenable.md --- title: Tenable --- runZero integrates with ((Tenable Vulnerability Management)) (previously ((Tenable.io))), ((Tenable Nessus)), and ((Tenable Security Center)) to enrich your asset inventory and gain visibility into vulnerabilities detected in your environment. The [Tenable Vulnerability Management](docs/tenable-vm.md), [Nessus Professional](docs/tenable-nessuspro.md), and [Tenable Security Center](docs/tenable-sc.md) integrations pull data from the Tenable API, while all versions of [Tenable Nessus](docs/tenable-nessus.md) and Tenable Security Center (previously ((Tenable.sc))) are also supported through Nessus v2 file imports (`.nessus`). Note that at this time, only the main [Tenable Vulnerability Management](https://www.tenable.com/products/tenable-io/) cloud API endpoint at `https://cloud.tenable.com` is supported as an API integration. ## Asset inventory {#tenable-asset-inventory} There is a column on the asset inventory page showing the count of vulnerabilities detected by Tenable for each asset. When a single asset is selected, the vulnerabilities table lists all the results related to that asset. The vulnerability count can be impacted by the type of vulnerability scan as well as the import settings selected. ## Vulnerabilities table {#tenable-vulnerabilities-table} The **Vulnerabilities** tab of the inventory lists all vulnerability results that have been imported from Tenable. The table lists every result, and selecting a result will take you to the page for the impacted asset. ## Severity and risk scores {#tenable-scoring} Tenable uses the third-party Common Vulnerability Scoring System (CVSS) values from the National Vulnerability Database (NVD) to describe severity associated with vulnerabilities. Tenable assigns all vulnerabilities a severity rating (Info, Low, Medium, High, or Critical) based on the vulnerability's static CVSSv2 or CVSSv3 score. By default, Tenable uses CVSSv2, however users can opt to use CVSSv3 instead. runZero displays the CVSSv2-based severity in the Inventory and Asset views. To supplement the severity ratings, Tenable calculates a dynamic Vulnerability Priority Rating (VPR) for most vulnerabilities. The VPR is a dynamic companion to the data provided by the vulnerability's CVSS score, since Tenable updates the VPR to reflect the current threat landscape. VPR values range from 0.1-10.0, with a higher value representing a higher likelihood of exploit. runZero displays the VPR-based risk in the Inventory and Asset views. For more details about how Tenable handles severity and risk, please refer to their [documentation](https://docs.tenable.com/tenablesc/Content/RiskMetrics.htm). --- docs/tenable-vm.md --- title: Tenable Vulnerability Management aliases: ["/docs/tenable-io/"] --- runZero integrates with Tenable Vulnerability Management (previously ((Tenable.io))) by importing data from the Tenable [API](https://developer.tenable.com/docs/welcome/). ## Getting started with Tenable Vulnerability Management {#tenablevm-getting-started} To set up an integration with Tenable Vulnerability Management, you'll need to: 1. Create an Administrator API key in an access group with `Can View` [permission](https://developer.tenable.com/docs/permissions) to `Manage Assets`. Optionally, this must have the Scan Manager role in order to retrieve agent health data. 2. Configure the Tenable Vulnerability Management credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the integration to pull your data into runZero. ## Requirements {#tenablevm-requirements} Before you can set up the Tenable Vulnerability Management integration: * Make sure you have administrator access to the Tenable portal. ## Step 1: Create an Administrator API key {#tenablevm-step1} 1. Sign in to Tenable Vulnerability Management with the Administrator account being used for the runZero integration. 2. Go to **My Profile** > **My Account** > **API Keys**. 3. **Generate** the API token, and then download or copy it. ## Step 2: Add the Tenable credential to runZero {#tenablevm-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Tenable Vulnerability Management`. 2. Choose **Tenable.io Access & Secret** from the list of credential types. 3. Generate your Tenable access and secret keys via your account page in the Tenable portal, and then provide the following information: * **Access key** - Your 64-character Tenable access key. * **Secret key** - Your 64-character Tenable secret key. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Tenable Vulnerability Management. ## Step 3: Choose how to configure the Tenable integration {#tenablevm-step3} The Tenable Vulnerability Management integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. Setting up a connector will work if you're self-hosting runZero or integrating with Tenable Vulnerability Management. ## Step 4: Set up and activate the integration to sync data {#tenablevm-step4} After you add your Tenable credential, you'll need to sync your data from Tenable Vulnerability Management. ### Step 4a: Configure the Tenable integration as a connector task {#tenablevm-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Tenable-only assets are created. 1. Activate a connection to [Tenable Vulnerability Management](https://console.runzero.com/ingest/tenable). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. If you want to exclude assets that have not been scanned by runZero from your integration import, check the **Exclude assets that cannot be merged into an existing asset** checkbox. By default, the integration will include assets that have not been scanned by runZero. 1. If you want to include assets that have not been assessed for vulnerabilities, check the **Include assets that have not been assessed for vulnerabilities** checkbox. 1. If you want to exclude retrieving asset agent health data, check the **Disable importing asset agent data** checkbox. 1. Check the **Disable importing software from the Tenable inventory** checkbox if you want software records to be ingested for fingerprint analysis but not stored in your runZero software inventory (optional). 1. Check the **Disable importing vulnerabilities from the Tenable inventory** checkbox if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 1. Set the [severity and risk levels](docs/tenable.md/#tenable-scoring) you want to import (optional). **Note**: Much of the host information provided by Tenable is from Info-level plugins, so if you only import higher levels of severity you may not see much information about assets not scanned by runZero. 1. Optionally provide a list of tags to include in the import. The list should be comma separated and use the format `category:value`. We will import assets that match at least one of the specified tags. 1. To filter by asset source, set the **Filter by asset source** option to either _All supported sources_ or a combination of sources from the checklist. 1. Enter a name for the task, like `Tenable Vulnerability Management sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 1. Enter a description for the task (optional). 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Tenable integration as a scan probe {#tenablevm-step4b} You can run the Tenable Vulnerability Management integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. In a new or existing scan configuration: * Ensure that the _TENABLE_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Optionally, set the [severity and risk levels](docs/tenable.md/#tenable-scoring) for ingested vulnerability scan results. * Set the correct `Tenable` credential to _Yes_ in the _Credentials_ tab. ### Step 5: View Tenable assets and vulnerabilities {#tenablevm-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Tenable assets. These assets will have a Tenable icon listed in the **Source** column. The Tenable integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to **Inventory** > [**Vulnerabilities**](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Tenable Vulnerability Management. To filter by Tenable assets, consider running the following queries: * [View all Tenable assets](https://console.runzero.com/inventory?search=source%3Atenable): ``` source:Tenable ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Tenable scan data. ## Troubleshooting {#tenablevm-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Tenable Vulnerability Management integration unable to connect? {#tenablevm-connection-error} 1. Are you getting any data from the Tenable Vulnerability Management integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Tenable Vulnerability Management integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Tenable host if it is on-premises. ### How do I solve the following error in Tenable Vulnerability Management: {#tenablevm-import-error} ``` "error-message":"no tenable assets match import criteria", "level":"error","msg":"could not load scan result data to writer" ``` This is an error we have seen intermittently from Tenable. A solution that usually works is to enable the _Include Unscanned Assets_ toggle in the Tenable task configuration. This will disable the filters we apply for live assets that were scanned in the last 30 days. --- docs/tenable-nessuspro.md --- title: Nessus Professional --- runZero integrates with ((Nessus Professional|Tenable Nessus Professional)) by importing data from the Tenable [API](https://developer.tenable.com/docs/welcome/). ## Getting started with Nessus Professional {#nessuspro-getting-started} To set up an integration with ((Nessus Professional)), you'll need to: 1. Create an Administrator API key in an access group with _Can View_ [permission](https://developer.tenable.com/docs/permissions) to _Manage Assets_. 2. Configure the Nessus Professional credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the integration to pull your data into runZero. ## Requirements {#nessuspro-requirements} Before you can set up the Nessus Professional integration: * Make sure you have administrator access to the Nessus Professional portal. ## Step 1: Create an Administrator API key 1. Sign in to Nessus Professional with the Administrator account being used for the runZero integration. 2. Go to **My Profile** > **My Account** > **API Keys**. 3. **Generate** the API token, and then download or copy it. * You will either need to configure the Tenable credential to skip TLS verification, or provide the TLS thumbprint when creating the runZero credential. ## Step 2: Add the Nessus Professional credential to runZero 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Nessus Professional`. 2. Choose **Nessus Professional Access & Secret** from the list of credential types. 3. Generate your Tenable access and secret keys via your account page in the Tenable portal, and then provide the following information: * **Access key** - Your 64-character Tenable access key. * **Secret key** - Your 64-character Tenable secret key. * **Nessus API URL** - The API URL for your Nessus Professional instance. The expected format is `https://ip:port` or `https://domain.tld:port`. The default port used by Nessus Professional is `8834`. * **Nessus insecure** - Set this to _Yes_ if you want to attempt authentication without a verified thumbprint. * **Nessus thumbprints** (optional) - A set of IP=SHA256:B64HASH pairs to trust for authentication. * You will need to scan your Nessus instance with runZero in order to obtain the TLS thumbprint. The [TLS fingerprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=tls.fp.sha256&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20[tls.fp.sha256]) lists all previously seen fingerprints. * If _Nessus insecure_ is set to _No_ and no thumbprints are provided: * With a self-signed certificate, the connection will fail because the certificate chain cannot be verified. * With a valid certificate from a public CA, the connection can work without thumbprints. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Nessus Professional. ## Step 3: Choose how to configure the Nessus Professional integration The Nessus Professional integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. Setting up a connector will work if you're self-hosting runZero or your Nessus Professional instance is publicly accessible. ## Step 4: Set up and activate the integration to sync data After you add your Tenable credential, you'll need to sync your data from Nessus Professional. ### Step 4a: Configure the Nessus Professional integration as a connector task A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Tenable-only assets are created. 1. Activate a connection to [Nessus Professional](https://console.runzero.com/ingest/nessus). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Set the [severity and risk levels](docs/tenable.md/#tenable-scoring) you want to import (optional). **Note**: Much of the host information provided by Tenable is from Info-level plugins, so if you only import higher levels of severity you may not see much information about assets not scanned by runZero. 4. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 5. Enter a name for the task, like `Nessus Professional sync` (optional). 6. Choose the Explorer to perform this connector task from (optional). 7. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 8. Enter a description for the task (optional). 9. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 10. If you want to include assets that have not been assessed for vulnerabilities, switch the **Include unscanned assets** toggle to _Yes_. 11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Nessus Professional integration as a scan probe You can run the Nessus Professional integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. In a new or existing scan configuration: * Ensure that the _NESSUS_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Set the correct _Nessus_ credential to _Yes_ in the _Credentials_ tab. * Optionally, set the [severity and risk levels](docs/tenable.md/#tenable-scoring) for ingested vulnerability scan results. ### Step 5: View Tenable assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Tenable assets. These assets will have a Tenable icon listed in the **Source** column. The Tenable integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Nessus Professional. To filter by Tenable assets, consider running the following queries: * [View all Tenable assets](https://console.runzero.com/inventory?search=source%3Atenable): ``` source:Tenable ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Tenable scan data. ## Troubleshooting {#nessuspro-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Nessus Professional integration unable to connect? {#nessuspro-connection-error} 1. Are you getting any data from the Nessus Professional integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the Nessus Professional integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the Tenable host if it is on-premises. ### How do I solve the following error in Nessus Professional: * `"error-message":"no tenable assets match import criteria","level":"error","msg":"could not load scan result data to writer"` {#nessuspro-import-error} This is an error we have seen intermittently from Tenable. A solution that usually works is to enable the _Include Unscanned Assets_ toggle in the Tenable task configuration. This will disable the filters we apply for live assets that were scanned in the last 30 days. --- docs/tenable-nessus.md --- title: Tenable Nessus --- runZero integrates with ((Tenable Nessus)) using two methods. For all versions of ((Nessus)), runZero can import Nessus files (`.nessus`) that were exported from your Nessus instance. Exports from Tenable Security Center are also supported. For Nessus Professional users, the runZero integration can pull scan data from the [Nessus Professional API](docs/tenable-nessuspro.md). ## Getting started with Tenable Nessus {#nessus-getting-started} To use the Tenable Nessus integration, you'll need to: 1. Export vulnerability scan results as Nessus files. 2. Import the Nessus files through the inventory pages. ## Requirements {#nessus-requirements} Before you can set up the Nessus integration: * Make sure you have access to the Nessus portal. ### Step 1: Export vulnerability scan results 1. Sign in to Nessus with the account being used for the runZero integration. 2. Open the scan results you want to be able to import into runZero. 3. Choose **Export** > **Nessus** to download the scan results. ### Step 2: Import the Nessus files into runZero 1. Go to the [Inventory page](https://console.runzero.com/inventory) in runZero. 2. Choose **Import** > **Nessus scan (.nessus)** from the list of import types. 3. On the import data page: * Choose the site you want to add your assets to, and * Set the [severity levels and minimum risk level](docs/tenable.md/#tenable-scoring) to ingest. (**Note**: much of the host information provided by Tenable is from Info-level plugins, so if you only import higher levels of severity you may not see much information about assets not scanned by runZero.) ### Step 3: View Nessus assets and vulnerabilities After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Nessus assets. These assets will have a Tenable icon listed in the **Source** column. The Nessus integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Nessus. To filter by Nessus assets, consider running the following queries: * [View all Nessus assets](https://console.runzero.com/inventory?search=source%3Atenable): ``` source:Tenable ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Nessus scan file. ## Troubleshooting {#nessus-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Tenable Nessus integration unable to connect? 1. Are you getting any data from the Tenable Nessus integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. --- docs/tenable-sc.md --- title: Tenable Security Center aliases: ["/docs/tenable-sc/"] --- runZero integrates with Tenable Security Center (previously ((Tenable.sc))) by importing data from the Tenable Security Center [API](https://docs.tenable.com/security-center/api/). ## Getting started with Tenable Security Center {#tenablesc-getting-started} To set up an integration with Tenable Security Center, you'll need to: 1. Create an API key for a user that has access to view and query vulnerabilities in Tenable Security Center. 1. Configure the Tenable Security Center credential in runZero. 1. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 1. Activate the integration to pull your data into runZero. ## Requirements {#tenablesc-requirements} Before you can set up the Tenable Security Center integration: * Make sure you have administrator access to the Tenable Security Center portal. ## Step 1: Create an API key {#tenablesc-step1} 1. Sign in to Tenable Security Center with an Administrator account. 1. Make sure [API key authentication is enabled](https://docs.tenable.com/security-center/Content/EnableAPIKeys.htm) 1. Go to **Users** > **Users**. 1. Check the box for the user you want to create an API key for. **Note**: The API key will have the same access as the user you select. Make sure the user has access to view and query vulnerabilities in the desired organization. 1. At the top of the table, click the **API Keys** > **Generate API Key** option. 1. Click **Generate** to create the API token, and then download or copy it. ## Step 2: Add the Tenable Security Center credential to runZero {#tenablesc-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Tenable Security Center`. 1. Choose **Tenable Security Center Access & Secret** from the list of credential types. 1. Generate your Tenable Security Center API key as directed in [Step 1](#tenablesc-step1), and then provide the following information: * **Access key** - Your 64-character Tenable Security Center access key. * **Secret key** - Your 64-character Tenable Security Center secret key. 1. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 1. Save the credential. You're now ready to set up and activate the connection to bring in data from Tenable Security Center. ## Step 3: Choose how to configure the Tenable Security Center integration {#tenablesc-step3} The Tenable Security Center integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. If you are integrating with an internal Tenable Security Center instance, we recommend setting up a connector to run from one of your explorers. Otherwise, if you are integrating with an external-facing Tenable Security Center instance, you can set up a connector to run from the cloud. If you are self-hosting runZero, you can run the connector from an explorer or from your runZero host, whichever can reach your Tenable Security Center install. ## Step 4: Set up and activate the integration to sync data {#tenablesc-step4} After you add your credential, you'll need to sync your data from Tenable Security Center. ### Step 4a: Configure the Tenable Security Center integration as a connector task {#tenablesc-step4a} A connection requires you to specify a schedule which determines when the sync occurs. 1. Activate a connection to [Tenable Security Center](https://console.runzero.com/ingest/tenablesecuritycenter). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 1. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 1. Configure the _Tenable Security Center query mode_ setting (optional). * Select _Define filters_ to define a filter based on [vulnerability severity and risk level](docs/tenable.md/#tenable-scoring). **Note**: Much of the host information provided by Tenable is from Info-level plugins, so if you only import higher levels of severity you may not see much information about assets. * Select _Use existing query ID_ to provide the Tenable Security Center query to use. **Note**: The query must be the _Vulnerability_ type and use the _Vulnerability Detail List_ tool. 1. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 1. Enter a name for the task, like `Tenable Security Center sync` (optional). 1. Choose the Explorer to perform this connector task from (optional). 1. Choose the site you want to configure the connector for. 1. Enter a description for the task (optional). 1. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 1. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Tenable Security Center integration as a scan probe {#tenablesc-step4b} You can run the Tenable Security Center integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. In a new or existing scan configuration: * Ensure that the _TENABLESECURITYCENTER_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Optionally, set the [severity and risk levels](tenable.md/#tenable-scoring) for ingested vulnerability scan results or provide a query ID. * Set the correct `TenableSecurityCenter` credential to _Yes_ in the _Credentials_ tab. ### Step 5: View Tenable Security Center assets and vulnerabilities {#tenablesc-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Tenable Security Center assets. These assets will have a Tenable icon listed in the **Source** column. The Tenable Security Center integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to **Inventory** > [**Vulnerabilities**](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by Tenable Security Center. To filter by Tenable Security Center assets, consider running the following queries: * [View all Tenable Security Center assets](https://console.runzero.com/inventory?search=source%3Atenablesecuritycenter): ``` source:tenablesecuritycenter ``` * [View all Tenable Security Center vulnerabilities](https://console.runzero.com/inventory/vulnerability?search=source%3Atenablesecuritycenter): ``` source:tenablesecuritycenter ``` Click into each asset or vulnerability to see its individual attributes. runZero will show you the attributes gathered from the Tenable Security Center API. --- docs/vmware.md --- title: VMware --- runZero Platform supports synchronization of ((VMware)) ((vCenter)) and ((ESXi)) ((virtual machine)) inventories. ## Setting up VMware credentials Unlike other APIs, the VMware synchronization process is configured as part of your regular runZero Explorer scans. The first step is to set up a set of VMware credentials. On the [Scanning with credentials](https://console.runzero.com/credentials) page, click _Add Credential_ and choose a credential type of _VMware vCenter/ESXi Username and Password_, and enter the appropriate username and password. The correct username syntax in most cases is `user@domain.com`. The VMware account used requires at least **read-only** access. The CIDR allow list field can be used to limit which addresses the credentials should be sent to. This helps ensure that they are not passed to unexpected VMware systems that the runZero Explorer encounters on the network. If runZero has previously found VMware API endpoints, the optional _VMware thumbprints_ field will list their IP addresses and TLS fingerprints. You can edit this list to remove any systems you do not want to trust with your VMware credentials. Alternatively, if you do not want to limit authentication to the set list of IP addresses and TLS certificates, you can set _VMware insecure_ to _Yes_ to approve authenticating with untrusted endpoints. The organization access for the credentials can be set as for any other stored credentials; see [Scanning with credentials](scanning-credentials.md). ## Performing VMware synchronization Once you have defined a set of VMware credentials, the second step is to enable VMware synchronization as part of a scan task. Any task which includes scanning the VMware host systems can be used to synchronize VMware VM data. The Probes tab of the scan setup has a section for enabling and disabling the VMware probe. The probe must be enabled for VMware synchronization to work; it is enabled by default. On the Credentials tab of the scan setup, use the toggle switch to enable the appropriate set of VMware vCenter/ESXi credentials. When the scan runs, the Explorer will use the credentials to authenticate with any VMware ESXi or vCenter hosts it finds that the credentials are configured to trust. Data about assets which are VMware VMs will be imported into runZero automatically, and merged with the other information runZero finds by scanning. ## Troubleshooting {#vmware-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the VMware integration unable to connect? 1. Are you getting any data from the VMware integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. 3. If the VMware integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue 4. Verify you are running the integration task from an Explorer with access to the VMware host if it is on-premises. --- docs/wiz.md --- title: Wiz --- runZero integrates with ((Wiz)) by importing data from the [Wiz API](https://docs.wiz.io/wiz-docs/docs/wiz-api-introduction). This integration allows you to sync data about your cloud assets, software, and vulnerabilities from Wiz to provide better visibility of your cloud assets and security posture. ## Getting started with Wiz {#wiz-getting-started} To set up an integration with Wiz, you'll need to: 1. Create a Service Account in Wiz with permissions to read graph resources, read reports, and create reports. 2. Configure the Wiz credential in runZero. 3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector). 4. Activate the integration to pull your data into runZero. ## Requirements {#wiz-requirements} Before you can set up the Wiz integration: * Make sure you have administrator access to the Wiz portal. ## Step 1: Create a Service Account in Wiz {#wiz-step1} 1. Sign in to Wiz with an Administrator account. 2. Go to **Settings** > **Access Management** > **Service Accounts** > **Add Service Account**. 3. Enter a descriptive name in the **Name** field. 4. Select _Custom Integration (GraphQL API)_ for the **Type**. 5. Under **Projects**, select the projects the Service Account should have access to, or leave blank to allow access to all projects. 6. Enable `read:resources`, `read:reports`, and `create:reports` for the **API Scopes**. 7. Click **Add Service Account** and copy the **Client ID** and **Client Secret**. 8. Go to **User Settings** > **Tenant** and note the **API Endpoint URL** in the format: `https://api.{{region}}.app.wiz.io/`. ## Step 2: Add the Wiz credential to runZero {#wiz-step2} 1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero. Provide a name for the credentials, like `Wiz`. 2. Choose **Wiz Client Secret** from the list of credential types. 3. Create your Wiz service account via the settings page in the Wiz portal, and then provide the following information: * **Wiz Client ID** - The client ID of your Wiz service account. * **Wiz Client Secret** - The client secret of your Wiz service account. * **Wiz Auth URL**- The URL used to authenticate the Wiz service account. * **Wiz API URL** - The API Endpoint URL used to access the Wiz API. 4. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 5. Save the credential. You're now ready to set up and activate the connection to bring in data from Wiz. ## Step 3: Choose how to configure the Wiz integration {#wiz-step3} The Wiz integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. ## Step 4: Set up and activate the integration to sync data {#wiz-step4} After you add your Wiz credential, you'll need to sync your data from Wiz. ### Step 4a: Configure the Wiz integration as a connector task {#wiz-step4a} A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Wiz-only assets are created. 1. Activate a connection to [Wiz](https://console.runzero.com/ingest/wiz). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 3. Set the severity and risk levels you want to import (optional). 4. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional). 5. Enter a name for the task, like `Wiz Sync` (optional). 6. Choose the Explorer to perform this connector task from (optional). 7. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. 8. Enter a description for the task (optional). 9. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero. 10. If you want to exclude assets that have not been assessed for vulnerabilities, switch the **Include unscanned assets** toggle to _No_. 11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur. ### Step 4b: Configure the Wiz integration as a scan probe {#wiz-step4b} You can run the Wiz integration as a scan probe so that the runZero Explorer will pull your Wiz assets into the runZero Console. In a new or existing scan configuration: * Ensure that the _WIZ_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. * Optionally, set the severity and risk levels for ingested vulnerability results. * Set the correct _Wiz_ credential to _Yes_ in the _Credentials_ tab. ### Step 5: View Wiz assets, software, and vulnerabilities {#wiz-step5} After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Wiz assets. These assets will have a Wiz icon listed in the **Source** column. The Wiz integration gathers details about software and vulnerabilities detected in addition to enriching asset inventory data. Go to **Inventory** > [**Software**](https://console.runzero.com/inventory/software) or **Inventory** > [**Vulnerabilities**](https://console.runzero.com/inventory/vulnerabilities) to view the software and vulnerability data provided by Wiz. To filter by Wiz assets, consider running the following queries: * [View all Wiz assets](https://console.runzero.com/inventory?search=source%3Awiz): ``` source:Wiz ``` Click into each asset to see its individual attributes. runZero will show you the attributes gathered from Wiz. ## Troubleshooting {#wiz-troubleshooting} If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting. ### Why is the Wiz integration unable to connect? {#wiz-connection-error} 1. Are you getting any data from the Wiz integration? * Make sure to query the inventory rather than look at the task details to review all the data available from this integration. * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console. 2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly. * Double-check the API Scopes assigned to the Wiz service account. A valid service account that is missing the required permissions will result in a failed import. 3. If the Wiz integration is unable to connect be sure to check the task log for errors. Some common errors include: * 500 - server error, unable to connect to the endpoint * 404 - hitting an unknown endpoint on the server * 403 - not authorized, likely a credential issue --- docs/integrations-outbound.md --- title: "Outbound integrations" --- ## Using runZero data to enrich other tools In addition to being able to enrich your runZero inventory with data from your [other IT and security tools](docs/integrations-inbound.md), the runZero platform offers [egress integrations with several platforms](https://console.runzero.com/integrations/). By leveraging product APIs and export/import functionality, runZero can provide additional asset context in other IT and security tools. The following integrations are available to send your runZero data into other platforms: ### IT service management * [Atlassian Insight & Jira Service Management](atlassian-jira-service-management.md) * [ServiceNow CMDB](servicenow-connector.md) ### Detection and investigation * [Panther](panther.md) * [Splunk Search](splunk.md) * [Sumo Logic](sumo-logic-siem.md) * [Tines](tines.md) * [Thinkst Canary](thinkst-canary.md) ### Vulnerabilities and risk {#integrations-outbound-vm} * [SecurityGate.io](securitygate.md) --- docs/atlassian-jira-service-management.md --- title: Atlassian Insight & Jira Service Management --- All runZero editions integrate with ((Jira Service Management)) via an import in ((Atlassian Insight)). runZero asset data is then imported into the CMDB. Follow these steps to perform a basic import. ## Step 1: Export runZero asset data You can export data using the **Export** button from the runZero inventory or the Export API. The following are sample commands for the export API that include common export fields but omit the tags field. You must replace the token `ETxxx...` with your account's export token from the [Inventory export API page](https://console.runzero.com/inventory/export_api). For a CSV export, use this command (one line): ``` curl -o "assets.csv" -H "Authorization: Bearer ETxxxxxxxxxxxxxxxxxxxxxxxxxxxx" "https://console.runzero.com:443/api/v1.0/export/org/assets.csv" ``` For a JSON export, use this command (one line): ``` curl -o "assets.json" -H "Authorization: Bearer ETxxxxxxxxxxxxxxxxxxxxxxxxxxxx" "https://console.runzero.com:443/api/v1.0/export/org/assets.csv" ```
Atlassian Insight does not accept any attribute longer than 255 characters and will produce errors if you are trying to import a file that contains longer fields. If you are seeing such errors, you may need to either trim or omit the fields.
## Step 2: Import data into Atlassian Insight You must use Jira Service Management Premium or Enterprise and have Atlassian Insight installed for the following steps to work. 1. In Jira Service Management, go to the Insight menu and click the **+** sign to create an object schema. 2. Name the object schema. In our example, we're calling it `Assets`. 3. Click on **...** next to the object schema and choose **Configuration**. 4. Go to the **Import** tab. 5. Click **Create Configuration**. ![Jira Service Management - Create import configuration](img/atlassian-1-2x.png) 6. Choose CSV or JSON, depending on your previous export and click **Next**. 7. Enter the name for your import. 8. In the **Concatenator** field, enter `\s`. ![Jira Service Management - Create import configuration 2](img/atlassian-2-2x.png) 9. Scroll down and click **Next**. 10. Choose the file you have previously exported form runZero. ![Jira Service Management - Create import configuration 2](img/atlassian-3-2x.png) 11. Click **Save Import Configuration**. 12. Click **Create predefined Insight structure** and wait for the task to finish. 13. Click **Create predefined configuration** and wait for the task to finish. ![Jira Service Management - Create import configuration 3](img/atlassian-4-2x.png) 14. Close the window. You will see a new entry with your configured import on the page. Click the settings cog and select **Execute Import**. ![Jira Service Management - Execute import](img/atlassian-5-2x.png) 15. Click **Import**. ![Jira Service Management - Confirm importing](img/atlassian-6-2x.png) 16. Your import was successful. Close the window. ![Jira Service Management - Finished process in action](img/atlassian-7-2x.png) If you are seeing the following error, one of your fields is longer than 255 characters. Manually trim the field to 255 characters or delete the field to successfully import your assets. ![Jira Service Management - Import error](img/atlassian-error-2x.png) ## Step 3: View your imported assets 1. In Jira Service Management, click on the Insights. 2. Click on your object schema. 3. Click on assets to view details. ![Jira Service Management - Imported assets](img/atlassian-8-2x.png) --- docs/panther.md --- title: Panther --- runZero data can be imported into your [Panther](https://panther.com/) instance for enhanced logging and alerting. ## Requirements {#panther-requirements} * A ((Panther)) account with the required permissions, * An AWS S3 bucket, and * Exported .jsonl files from runZero that have been uploaded into your AWS S3 bucket. ### Step 1: Adding a custom schema {#panther-custom-schema} 1. Go to **Configure > Schemas** and select **Create New**. 2. Add a name. 3. Upload a sample log to automatically parse the runZero output schema. ### Step 2: Adding a custom log source {#panther-custom-log-source} 1. Go to **Configure > Log Sources** and select **Create New**. 2. Complete the **Basic Information** section. 3. Opt to configure S3 prefixes and schemas now and select the custom schema you created. 4. Configure the IAM role: * Opt to configure **Using the AWS Console UI**. * Click **Launch Console UI**. * Review the stack in AWS, then check the box to approve, and click to deploy the stack. * When the deployment completes, navigate to the **Resources** tab and select the **LogProcessingRole** that was created. * Copy the ARN from that role into the field on the Panther console. 5. Configure an alarm if logs are not processed (optional). Once completed, any .jsonl files added to the specified AWS S3 bucket will be automatically ingested and processed by Panther. --- docs/securitygate.md --- title: SecurityGate.io aliases: ["/docs/set-up-securitygate/"] --- All runZero editions integrate with ((SecurityGate.io)) to enrich asset visibility in support of your risk assessment program. Setting up the integration requires a few steps in your SecurityGate.io console. ## Requirements {#securitygate-requirements} * Configuring the SecurityGate.io integration requires a [runZero API key](docs/managing-your-team.md#account-api-keys).
The SecurityGate.io integration will pull runZero asset data from across all organizations.
## Integrate runZero with SecurityGate.io 1. Sign in to your SecurityGate.io console. 2. Go to **My Account** under the **Hello** dropdown menu. 3. Click on **Integration Manager**. 4. Select **Add New Integration**. 5. Choose _Rumble_ from the **Integration Partner** dropdown menu. 6. Provide the **Account API Key**, **Server URL**, and **API Version**. 7. Click **Test Connection**. If the test is successful, click **OK** to save the configuration. ## Viewing runZero data in SecurityGate.io After the integration is enabled within SecurityGate.io, runZero data will be available through the Asset Inventory page. --- docs/servicenow-connector.md +++ title = "ServiceNow Service Graph" aliases = ["servicenow"] +++ The ((Service Graph connector)) for runZero allows you to bring runZero assets into your ((ServiceNow)) ((CMDB)) as CIs, and optionally periodically update the CIs with fresh information from runZero scans. The Service Graph Connector fetches and transforms data using ServiceNow ((IntegrationHub ETL)), and passes it through the Identification and Reconciliation Engine (((IRE))). This allows specific fields and CI class mappings to be fine-tuned from the ServiceNow console. You can also specify a runZero search query to determine which assets get brought in by the connector. ## Important notes - There is no charge from runZero for use of the connector. However, CI resources created in CMDB by the connector will increase ServiceNow Subscription Unit consumption. CIs created by Service Graph Connectors should be charged at a lower rate than CIs created via other means; you will need to consult ServiceNow to confirm this and obtain current pricing. - If you are a self-hosted runZero customer, you will need to set up a ((MID Server)) to enable ServiceNow to connect to your runZero console. If your console uses a self-signed TLS certificate, or a TLS certificate signed by your own internal CA, you will need to configure the MID server to accept the CA or certificate as trusted. For more information, see [ServiceNow Knowledge Base article KB0863673](https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0863673). - While the Service Graph Connector is packaged and available from the ServiceNow Application Store, setting up connectors to integrate with your existing ServiceNow configuration is unlikely to be a one-click operation. You are strongly advised to have a ServiceNow Consulting and Implementation partner available to assist with the process. - You can find the Scoped Application Installation and Configuration Guide on the [Service Graph Connector for runZero](https://store.servicenow.com/sn_appstore_store.do#!/store/application/4e389aa0874711100b3831583cbb3572/1.0.4) page under Supporting Links and Docs. This has detailed installation instructions with screenshots. ## Prerequisites {#servicenow-prereqs} To use the Service Graph connector for runZero, you need the following: * A Platform license for runZero. * A ServiceNow ((ITOM)) license including ITOM Discovery and ITOM Visibility. * Integration Commons for CMDB installed. The ServiceNow dependencies are checked as part of the connector installation process. ## Installation {#servicenow-installation} The first step of the installation is to locate the Service Graph connector for runZero in the ServiceNow Application Store, and follow the usual process to install it into your ServiceNow instance. The Service Graph connector adds a new menu entry **Service Graph connector for runZero** to the ServiceNow main menu. The module contains entries for **Setup**, **Data Sources**, **Scheduled Imports**, **Support**, and **System Import Sets**. You must have the **admin** role in ServiceNow to configure the connector. ## Setup {#servicenow-setup} The **Setup** menu offers a **Guided Setup** process to help you get up and running with the connector. There are three main stages to the setup process: 1. Configure the connection 2. Configure the mappings (optional) 3. Confgure the scheduled import (optional) ### Step 1: Configure the connection {#servicenow-step1} Configuring the connection consists of two steps: entering a runZero API key as credentials, and configuring connection options. #### Entering the API key The connector can use a runZero **Organization API** or **Export API** key. In either case, you can obtain the key by going to the [**Organizations**](https://console.runzero.com/organizations/) page in runZero and clicking on the organization containing the assets you want to bring into ServiceNow CMDB. Organization tokens begin with `OT`, export tokens begin with `ET`. In the **API Key Credentials** form, paste the runZero token into the field labeled **API Key**, and click **Update**. #### Configuring connection options For runZero cloud users, the default **HTTP connection** options should be correct. You can optionally add a **Search** string to the **Attributes** for the connection at the bottom of the form. If you do, this search will be passed to runZero to determine the set of assets to bring in to CMDB via the connector. Any search string should be in runZero [search query format](docs/search-query-syntax.md). You are strongly encouraged to test your search string in your [runZero asset inventory](https://console.runzero.com/inventory/). The **Connection** alias and **Base path** fields should be left as-is. (The connection alias groups together the connection settings and the API key credentials for the connector to use.) If you are self-hosting runZero, the **connection options** form is where you configure the MID server to use and specify the URL of your runZero console. Your console's fully-qualified hostname should be placed in the **Host** field. The hostname should match the hostname in the console's TLS certificate in order for the MID server to trust it, even if the TLS certificate is trusted by the MID server. Check the **Use MID server** box and select the MID server to use. ### Step 2: Configure the mappings (optional) {#servicenow-step2} The second step of setting up the connector allows you to customize the mapping of runZero data to CI classes, using the IntegrationHub ETL Transform Map Assistant. This stage can be skipped if you do not have special requirements for data mapping. ### Step 3: Configure the Scheduled Import (optional) {#servicenow-step3} The third step of setting up the connector is to set up a schedule for data import. Initially, you will want to test the connector setup with a one-off import. Once everything is configured correctly, you can create recurring imports. Scheduled imports are configured as regular ServiceNow tasks. This step can be skipped if you don't want to set up a scheduled import at this time. ## Notes on data mapping {#servicenow-notes} The object data models for ServiceNow CMDB and runZero are not an exact match. Some runZero data does not fit in any standard attributes available in CMDB, and in other cases runZero does not have data that CMDB expects. Review this list to understand how the connector will map runZero attributes to ServiceNow CMDB attributes: * IP addresses: ServiceNow CIs have an attribute which takes a single IP address. The connector places the first IP address in the CI attribute IP Address. The remaining addresses are created as `IP Address` CIs owned by the device CI. Each `IP Address` CI is given a `Description` indicating whether it has been scanned by runZero or not. **Note**: By default, ServiceNow does not show IP addresses owned by a device CI. It only shows IP addresses owned by a network adapter CI which is owned by the device CI. This is a known limitation of ServiceNow's default CMDB forms. runZero doesn't associate IP addresses with network adapters because the necessary information isn't generally known. In that situation, the CMDB connector development guide states that the IP addresses should be associated with the device CI. * **Names**: ServiceNow CIs have a single `Name` attribute, while runZero assets can have any number of names with runZero attempting to guess which are the best names and put them at the front of the list. The connector places the first name in the CI `Name` attribute. The first name which looks like a fully-qualified domain name is placed in the `Fully qualified domain name` attribute, and is used to compute a DNS Domain for CIs descended from Network Gear. The full list of names is placed in the `Description` attribute for reference. * **Serial numbers**: ServiceNow CIs have an attribute which takes a single serial number. The connector picks the first serial number for the `Serial Number` attribute, and then also performs a Serial Number Lookup operation to add the complete list of serial numbers with their associated type. * **Tags**: runZero assets can have any number of tags, which are either single tags such as `tag_name`, or tags with values in the format `tag=value`. These are placed in the `Key Value` class, and this class is then associated with the `Hardware` class. * **MAC addresses/Network Adapters**: As with IP addresses, ServiceNow has both a single-value `MAC Address` attribute, and an option to look up named MAC addresses to create Network Adapter objects. A runZero asset can have any number of MAC addresses, but since runZero does not run agent software on the scanned systems, it has no way to know the interface name associated with a given MAC address. The first MAC address is imported as the `MAC Address` attribute, and the entire set is imported via lookup as `Network Adapter` objects, with each being given a name made up by the MAC address and IP address (e.g. `00:00:00:00:00:00-127.0.0.1`) or the MAC address and hostname if the IP address is not available (e.g. `00:00:00:00:00:00-hostname`). If neither the IP address or hostname are available, the MAC address alone is used as the network adapter name. In some cases, runZero may not know the MAC address(es) of an asset. In this case, a zero MAC address (`00:00:00:00:00:00`) is added to satisfy ServiceNow requirements for some CI classes. * **Sites**: runZero sites represent distinct networks, which may or may not correspond to physical sites. They are imported as CMDB `Network Site` objects. * **Organizations**: The runZero organization has no obvious corresponding attribute in network hardware CIs. The organization name is incorporated into the `Description` of CIs. * **SNMP data**: The `snmp.sysDesc` attribute from runZero, if it exists, is also placed in the `Description`. --- docs/splunk.md --- title: Splunk Search --- runZero integrates with ((Splunk)) using a dedicated [Splunk Addon](https://splunkbase.splunk.com/app/6549/), compatible with Splunk 7, Splunk 8, and Splunk Cloud. With this add-on, you'll be able to pull new or updated hosts into a ((Splunk)) index, where you'll be able to analyze, visualize, and monitor them there. This add-on uses the [Splunk API](https://app.swaggerhub.com/apis/runZero/runZero/#/Splunk) from the runZero Network Discovery platform. It supports syncing assets into Splunk, with multiple inputs supported, global API key management, and optional search filters for each input. For example, you can track new assets as one input, and SMBv1 enabled assets as another input. To set up this add-on, you'll need an Export API or Organization API key, which you can generate from your Organization page in the runZero Console. ## Get the runZero add-on for Splunk 1. Sign in to Splunk. 2. Go to **Find More Apps**. 3. Search for `runZero Network Discovery`. 4. Install the add-on for runZero. 3. Splunk will prompt you to sign in again. After you log back in again, the add-on will be installed. You'll be able to open the runZero Asset Sync app. Splunk might also prompt you to restart your server. ## Asset sync modes Two asset sync modes are available: New Assets Only and All Updated Assets. You can export asset inventory that contains newly discovered assets or updated assets, since the last poll, in a sync-friendly format for Splunk. You can leverage the same capabilities from the Asset Sync API to pull data in Splunk, such as search filters, fields, and time-based checkpoints. Once data is pulled into Splunk, you can create Splunk inputs with filters. This allows you to sync specific assets with a certain protocol, discovery date, or open service. --- docs/sumo-logic-siem.md --- title: Sumo Logic --- All runZero editions integrate with ((Sumo Logic)) to enrich asset visibility and help you visualize your asset data. Setting up the integration requires a few steps in your Sumo Logic console. The integration can be set up to support two distinct purposes: * [Complete asset visibility](sumo-logic-assets.md) * [Targeted alerting and visualization](sumo-logic-alerts.md) ## Requirements {#sumo-logic-requirements} * A Sumo Logic account * A runZero account and [API key](leveraging-the-api.md). --- docs/sumo-logic-assets.md --- title: Sumo Logic asset export --- runZero integrates with ((Sumo Logic)) to make your asset inventory available directly in Sumo Logic. This article will show you how to export your runZero inventory into Sumo Logic for use within the SIEM. ## Integrating runZero with Sumo Logic Setting up the connection between Sumo Logic and runZero has three options with different configuration steps. **Option A: [Local script](#sumo-logic-local)** 1. [Create a Sumo Logic HTTP Source](#sumo-logic-local-source). 2. [Configure your host to run the provided script](#sumo-logic-local-script). **Option B: [AWS Lambda function](#sumo-logic-lambda)** 1. [Create a Sumo Logic HTTP Source](#sumo-logic-lambda-source). 2. [Configure the AWS Lambda function to run the provided script](#sumo-logic-lambda-script). **Option C: [Sumo Logic script source](#sumo-logic-script)** 1. [Install a Sumo Logic collector](#sumo-logic-script-collector). 2. [Create a Sumo Logic script source](#sumo-logic-script-create). Once your data is flowing into Sumo Logic, you can [start using](#sumo-logic-searches) the data in Sumo Logic. ## Option A: Local script {#sumo-logic-local} ### Step 1: Create a Sumo Logic HTTP Source {#sumo-logic-local-source} 1. After logging in to Sumo Logic, navigate to **Manage Data** > **Collection**. 2. Click **Add Collector** then select **Hosted Collector**. * Provide a name, such as `runZero Collector` and click **Save**. 3. If prompted to add a data source, click **OK**. Otherwise, find your Collector in the list and click **Add Source**. 4. Select the [**HTTP Logs and Metrics**](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/logs-metrics/) source. * Provide a name, such as `runZero Assets`, then click **Save**. 5. Copy the URL provided to use in [step 2](#sumo-logic-local-script). ### Step 2: Configure your host to run the provided script {#sumo-logic-local-script} 1. Identify the host you would like to run the script from. 2. Ensure the host has Python3 and Pipenv installed. 3. Save the script below to the host it will be run from. ```python #!/usr/bin/env python3 import json import requests import os # RUNZERO CONF RUNZERO_EXPORT_TOKEN = os.environ["RUNZERO_EXPORT_TOKEN"] HEADERS = {"Authorization": f"Bearer {RUNZERO_EXPORT_TOKEN}"} BASE_URL = "https://console.runZero.com/api/v1.0" # SUMO LOGIC CONF HTTP_ENDPOINT = os.environ["SUMO_HTTP_ENDPOINT"] def main(): url = BASE_URL + "/export/org/assets.json" assets = requests.get(url, headers=HEADERS) batchsize = 500 if len(assets.json()) > 0 and assets.status_code == 200: for i in range(0, len(assets.json()), batchsize): batch = assets.json()[i:i+batchsize] f = open("upload.txt", "w") f.truncate(0) for a in batch: json.dump(a, f) f.write("\n") f.close() r = open("upload.txt") requests.post(HTTP_ENDPOINT, data=r.read()) r.close() else: print(f"No assets found - status code from runZero API: {assets.status_code}") if __name__ == "__main__": main() ``` 4. Create your environment variables by running the following commands: * `export RUNZERO_EXPORT_TOKEN=XXX`: Use your runZero export API token, which can be obtained in your runZero console on an [organization detail page](https://console.runzero.com/organizations). Select the organization you wish to export data from, then click **Edit organization** to view the export API token. * `export SUMO_HTTP_ENDPOINT=XXX`: Use the Sumo Logic token obtained in [step 1](#sumo-logic-local-source). 5. Create your virtual environment to run the script by running `pipenv --python /path/to/python3`. 6. Install the `requests` library in your virtual environment for making API calls: * `pipenv shell` * `pip install requests` 7. Test the script by running your script from the virtual environment. * Use the location from the `pipenv` output to start. * Append `/bin/python3` to use Python in the virtual environment. * Use the full path to the script. ```shell my-server:~/ $ /home/user/.local/share/virtualenvs/runZero-scripts-mVQtFLDO/bin/python3 \ /home/user/scripts/script.py ``` 8. Configure a crontab task to run at the desired cadence. * On the hour: `0 * * * * RUNZERO_EXPORT_TOKEN=XXX SUMO_HTTP_ENDPOINT=XXX /path/to/virtual/env/python3 /path/to/script.py` * Daily at midnight: `0 0 * * * RUNZERO_EXPORT_TOKEN=XXX SUMO_HTTP_ENDPOINT=XXX /path/to/virtual/env/python3 /path/to/script.py` * Weekly at midnight on Monday: `0 0 * * 1 RUNZERO_EXPORT_TOKEN=XXX SUMO_HTTP_ENDPOINT=XXX /path/to/virtual/env/python3 /path/to/script.py` ## Option B: AWS Lambda function {#sumo-logic-lambda} ### Step 1: Create a Sumo Logic HTTP Source {#sumo-logic-lambda-source} 1. After logging in to Sumo Logic, go to **Manage Data** > **Collection**. 2. Click **Add Collector** then select **Hosted Collector**. * Provide a name, such as `runZero Collector` and click **Save**. 3. If prompted to add a data source, click **OK**. Otherwise, find your Collector in the list and click **Add Source**. 4. Select the [**HTTP Logs and Metrics**](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/logs-metrics/) source. * Provide a name, such as `runZero Assets`, then click **Save**. 5. Copy the URL provided to use in [step 2](#sumo-logic-lambda-script). ### Step 2: Configuring the AWS Lambda function to run the provided script {#sumo-logic-lambda-script} 1. Go to your AWS Console and navigate to the [Lambda page](https://us-east-1.console.aws.amazon.com/lambda/home). 2. Click [**Create a function**](https://us-east-1.console.aws.amazon.com/lambda/home?region=us-east-1#/create/function?firstrun=true). 3. Give your function a **name**. 4. Select _Python 3.9_ as the **runtime**. 5. Everything else can be left with the default setting. Click **Create function** to move to the next page. 6. Click **Add Trigger** to set up a cron job. 7. Select _EventBridge_ to set up a schedule. 8. Use an existing rule or select **Create new rule**. * Give it a name and set **Rule type** to `Schedule expression`. * Use one of these options or create your own based on desired cadence: * Daily: `rate(1 day)` * Every 12 hours: `rate(12 hours)` * Every 3 hours: `rate(3 hours)` * Click **Add** to return to the main Lambda configuration page. 9. Under **Configuration** select _Environment variables_. 10. Enter these two environment variables: * `RUNZERO_EXPORT_TOKEN` which can be obtained in your runZero console on an [organization detail page](https://console.runzero.com/organizations). Select the organization you wish to export data from, then click **Edit organization** to view the export API token. * `SUMO_HTTP_ENDPOINT` which was obtained in [step 1](#sumo-logic-lambda-source). 11. Click _Save_ to return to the main Lambda configuration page. 12. Click the _Code_ tab and replace the default code with this script. ```python import json import urllib3 import os # RUNZERO CONF RUNZERO_EXPORT_TOKEN = os.environ["RUNZERO_EXPORT_TOKEN"] HEADERS = {"Authorization": f"Bearer {RUNZERO_EXPORT_TOKEN}"} BASE_URL = "https://console.runZero.com/api/v1.0" # SUMO LOGIC CONF HTTP_ENDPOINT = os.environ["SUMO_HTTP_ENDPOINT"] def lambda_handler(event, context): http = urllib3.PoolManager() url = BASE_URL + "/export/org/assets.json" response = http.request("GET", url, headers=HEADERS) data = response.data assets = json.loads(data) batchsize = 500 if len(assets.json()) > 0 and assets.status_code == 200: for i in range(0, len(assets.json()), batchsize): batch = assets.json()[i : i + batchsize] f = open("upload.txt", "w") f.truncate(0) for a in batch: json.dump(a, f) f.write("\n") f.close() r = open("upload.txt") http.request("POST", HTTP_ENDPOINT, data=r.read()) r.close() else: print(f"No assets found - status code from runZero API: {assets.status_code}") ``` 13. Click **Deploy** to update the code. 14. Click **Test** to verify the code works. Your asset data export will now be posted to Sumo Logic at the cadence you configured. ## Option C: Sumo Logic script source {#sumo-logic-script} ### Step 1: Installing a Sumo Logic collector {#sumo-logic-script-collector} Follow the [Sumo Logic documentation](https://help.sumologic.com/docs/send-data/installed-collectors/) in order to install a collector. ### Step 2: Creating a Sumo Logic script source {#sumo-logic-script-create} Sumo Logic has documentation on [script sources](https://help.sumologic.com/docs/send-data/installed-collectors/sources/script-source/) as well. Here are the steps to follow to set up the script source once your collector is installed. 1. Navigate to the [Collection](https://service.us2.sumologic.com/ui/#/collection/collection) page in Sumo Logic. 2. Find your collector and click **Add** > **Add Source**. 3. Select `Script` as the **source type**. 4. Input a `Name` and `Source Category`. 5. Select a `Frequency`. 6. Select **Command** type `/usr/bin/python`. 7. Add the following script in the **Script** field. ```python #!/usr/bin/python import json import requests import os # RUNZERO CONF RUNZERO_EXPORT_TOKEN = os.environ['RUNZERO_EXPORT_TOKEN'] HEADERS = {'Authorization': 'Bearer ' + RUNZERO_EXPORT_TOKEN} BASE_URL = 'https://console.runZero.com/api/v1.0' def main(): url = BASE_URL + '/export/org/assets.json' assets = requests.get(url, headers=HEADERS) if assets.status_code == 200: for a in assets.json(): print(json.dumps(a)) else: print(f"No assets found - status code from runZero API: {assets.status_code}") if __name__ == '__main__': main() ``` 8. Click **Save** to allow the source to start working. ## Working with the asset data in Sumo Logic {#sumo-logic-searches} Once your asset data in in Sumo Logic, you can use it in any way you would use any other log source. Here are some sample searches that you could use to create scheduled searches and dashboards. ### Search distinct assets ```shell _sourceCategory="runzero" | json field=_raw "id" | count_distinct(id) as distinct_assets ``` ### Search assets with more than 3 services running ```shell _sourceCategory="runzero" | json field=_raw "addresses_extra" | json field=_raw "addresses" | json field=_raw "id" | concat("https://console.runzero.com/inventory/", id) as runzero_link | json field=_raw "service_count" | where service_count > 3 | count addresses, addresses_extra, service_count, runzero_link ``` ### Determine counts of different operating systems ```shell _sourceCategory="runzero" | json field=_raw "os" | where !isEmpty(os) | json field=_raw "id" | count os, id | count os ``` --- docs/sumo-logic-alerts.md --- title: Sumo Logic alerting aliases: [ "/docs/sumo-logic/" ] --- runZero integrates with ((Sumo Logic)) to help you visualize your asset data. This helps you track your progress on reducing risk in your asset inventory over time. Setting up the connection between Sumo Logic and runZero requires: 1. [Creating a Sumo Logic HTTP Source](#sumo-logic-http-source) 2. [Creating a runZero alert template](#sumo-logic-alert-template) 3. [Creating a rule in runZero](#sumo-logic-rule) 4. [Handling runZero data in Sumo Logic](#sumo-logic-handling) 5. [Creating a Sumo Logic dashboard (optional)](#sumo-logic-dashboard) ## Step 1: Create a Sumo Logic HTTP Source {#sumo-logic-http-source} 1. After logging in to Sumo Logic, navigate to **Manage Data** > **Collection**. 2. Click **Add Collector** select **Hosted Collector**, provide a name, such as `runZero Collector` and click **save**. 3. If prompted to add a data source, click **OK**. Otherwise, find your Collector in the list and click **Add Source**. 4. Select the [**HTTP Logs and Metrics**](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/logs-metrics/) source, provide a name, such as `runZero Alerts`, and then click **save**. 5. Copy the URL provided to use in [step 2](#sumo-logic-alert-template). ## Step 2: Create a runZero alert template {#sumo-logic-alert-template} 1. Create an [alert template](https://console.runzero.com/alerts/template/create/) in runZero and provide the following details: * **Name**: Name for template * **Template type**: JSON * **Subject line for message**: Leave empty * **Body of message**: The following JSON example will include the rule name and the search URL in the alert message body ```plaintext {"rule_name":"{{rule.name}}","search_url":"{{search.url}}","found": "{{search.found}}", "assets_new": "{{scan.assets_new}}"} ``` 2. Create an [alert channel](https://console.runzero.com/alerts/channel/create/) in runZero and provide the following details: * **Name**: Name for alert channel * **Channel type**: Webhook * **Webhook URL**: The webhook URL you copied from Sumo Logic ## Step 3: Create a rule in runZero {#sumo-logic-rule} Now that you have your alert template and channel created, you will want to identify the triggers to alert on. Some common examples are: * Asset query results - When there is a match on a query in runZero after a scan completes * New assets found - When a scan completes with new assets * Agent offline - When your runZero Explorer stops checking in to the console * Task failed - When a task fails for any reason. We will use the **asset query results** selection as an example for the rest of the steps. Review [example queries](docs/search-query-examples.md) for ideas on what queries you could create. 1. Create a [new alert rule](https://console.runzero.com/alerts/rule/create/). 2. Select `asset-query-results` and click **Configure rule**. 3. Input values for the rule: * **Name**: name of the rule. * **Conditions**: optional parameters that will trigger the alert when all conditions match. * **Query**: The query the assets must match. * **Number of matches**: The numeric comparison logic for the **value**. * **Value**: The threshold of matches to trigger the rule. * **Limit to organization**: Allows you to limit the alert to a specific organization. * **Limit to site**: Allows you to limit the alert to a specific site. * **Action**: `Notify` * **Notification channel**: Name of the alert channel you created in step 2. * **Notification template**: Name of the alert template you created in step 2. ## Step 4: Handle runZero data in Sumo Logic {#sumo-logic-handling} ### This search will display the raw runZero data ```code _source="runZero Alerts" and _collector="runZero" ``` ### This search will show alerts matching the runZero rule name ```code _source="runZero Alerts" and _collector="runZero" | json field=_raw "found" nodrop | json field=_raw "rule_name" nodrop | where rule_name = "" ``` ### This search will create a graph of the data matching the runZero rule name ```code _source="runZero Alerts" and _collector="runZero" | json field=_raw "assets_new" nodrop | toLong(assets_new) | json field=_raw "found" nodrop | json field=_raw "search_url" nodrop | json field=_raw "rule_name" nodrop | where rule_name = "" | timeslice 1m | sum(found) by _timeslice | order by _timeslice ``` ## Step 5: Create a dashboard in Sumo Logic (optional) {#sumo-logic-dashboard} Now that you know how to look at the data in Sumo Logic and make a graph, you can follow these steps to create a dashboard. You will first create four rules in runZero, then you will import the [Sample Sumo Logic Dashboard](#sumo-logic-dash) below. ## Create the runZero rules You will follow the same actions from step 3 to create each of these rules using the form inputs provided. ### Assets running a TLS service * **Rule type**: asset-query-results * **Name**: `Assets running a TLS service - Sumo` * **Query**: `alive:t protocol:tls` * **Number of matches**: is greater than 0 * **Notification channel**: alert channel created in [Step 2](#sumo-logic-alert-template) * **Notification template**: alert template created in [Step 2](#sumo-logic-alert-template) ### Multihomed assets - Sumo * **Rule type**: asset-query-results * **Name**: `Multihomed assets - Sumo` * **Query**: `alive:t AND multi_home:t` * **Number of matches**: is greater than 0 * **Notification channel**: alert channel created in [Step 2](#sumo-logic-alert-template) * **Notification template**: alert template created in [Step 2](#sumo-logic-alert-template) ### Assets with OpenSSL - Sumo * **Rule type**: asset-query-results * **Name**: `Assets with OpenSSL - Sumo` * **Query**: `alive:t product:openssl` * **Number of matches**: is greater than 0 * **Notification channel**: alert channel created in [Step 2](#sumo-logic-alert-template) * **Notification template**: alert template created in [Step 2](#sumo-logic-alert-template) ### New assets to Sumo Logic * **Rule type**: new-assets-found * **Name**: `New assets to Sumo Logic` * **Number of matches**: is greater than 0 * **Notification channel**: alert channel created in [Step 2](#sumo-logic-alert-template) * **Notification template**: alert template created in [Step 2](#sumo-logic-alert-template) ## Sample Sumo Logic Dashboard {#sumo-logic-dash} 1. Navigate to the library in Sumo Logic. 2. Click the **options** button on the folder you'd like to import to and click `Import`. * **Name**: runZero Alert Metrics * **JSON**: Copy from the sample below 3. Click `Import` to see this dashboard under the folder it was imported to. ```json { "type": "DashboardV2SyncDefinition", "name": "runZero Asset Metrics", "description": "", "title": "runZero Asset Metrics", "theme": "Dark", "topologyLabelMap": { "data": {} }, "refreshInterval": 0, "timeRange": { "type": "BeginBoundedTimeRange", "from": { "type": "RelativeTimeRangeBoundary", "relativeTime": "-3d" }, "to": null }, "layout": { "layoutType": "Grid", "layoutStructures": [ { "key": "panelPANE-AC8FB3DCBD32DA48", "structure": "{\"height\":6,\"width\":12,\"x\":0,\"y\":0}" }, { "key": "panel3D084A3284252A4E", "structure": "{\"height\":6,\"width\":12,\"x\":12,\"y\":0}" }, { "key": "panelPANE-4389DBF794B13B44", "structure": "{\"height\":6,\"width\":12,\"x\":0,\"y\":6}" }, { "key": "panelPANE-FBE08549B2123A4A", "structure": "{\"height\":6,\"width\":12,\"x\":12,\"y\":6}" } ] }, "panels": [ { "id": null, "key": "panelPANE-AC8FB3DCBD32DA48", "title": "New assets found", "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"series\":{},\"overrides\":[]}", "keepVisualSettingsConsistentWithParent": true, "panelType": "SumoSearchPanel", "queries": [ { "transient": false, "queryString": "_source=\"runZero Alerts\" and _collector=\"runZero\"\n| json field=_raw \"assets_new\" nodrop\n| json field=_raw \"found\" nodrop\n| json field=_raw \"search_url\" nodrop\n| json field=_raw \"rule_name\" nodrop\n| where rule_name = \"New Assets to Sumo Logic\"\n| timeslice 1m\n| sum(assets_new) by _timeslice\n| order by _timeslice", "queryType": "Logs", "queryKey": "A", "metricsQueryMode": null, "metricsQueryData": null, "tracesQueryData": null, "spansQueryData": null, "parseMode": "Auto", "timeSource": "Message", "outputCardinalityLimit": 1000 } ], "description": "", "timeRange": null, "coloringRules": null, "linkedDashboards": [] }, { "id": null, "key": "panel3D084A3284252A4E", "title": "Multihomed assets found", "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"series\":{},\"overrides\":[]}", "keepVisualSettingsConsistentWithParent": true, "panelType": "SumoSearchPanel", "queries": [ { "transient": false, "queryString": "_source=\"runZero Alerts\" and _collector=\"runZero\"\n| json field=_raw \"assets_new\" nodrop\n| toLong(assets_new)\n| json field=_raw \"found\" nodrop\n| json field=_raw \"search_url\" nodrop\n| json field=_raw \"rule_name\" nodrop\n| where rule_name = \"Multihomed Assets\" or rule_name = \"Multihomed Assets - Sumo\"\n| timeslice 1m\n| sum(found) by _timeslice\n| order by _timeslice", "queryType": "Logs", "queryKey": "A", "metricsQueryMode": null, "metricsQueryData": null, "tracesQueryData": null, "spansQueryData": null, "parseMode": "Auto", "timeSource": "Message", "outputCardinalityLimit": 1000 } ], "description": "", "timeRange": null, "coloringRules": null, "linkedDashboards": [] }, { "id": null, "key": "panelPANE-4389DBF794B13B44", "title": "Assets with a TLS service", "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"series\":{},\"overrides\":[]}", "keepVisualSettingsConsistentWithParent": true, "panelType": "SumoSearchPanel", "queries": [ { "transient": false, "queryString": "_source=\"runZero Alerts\" and _collector=\"runZero\"\n| json field=_raw \"assets_new\" nodrop\n| toLong(assets_new)\n| json field=_raw \"found\" nodrop\n| json field=_raw \"search_url\" nodrop\n| json field=_raw \"rule_name\" nodrop\n| where rule_name = \"Assets running a TLS service\" or rule_name = \"Assets running a TLS service - Sumo\"\n| timeslice 1m\n| sum(found) by _timeslice\n| order by _timeslice", "queryType": "Logs", "queryKey": "A", "metricsQueryMode": null, "metricsQueryData": null, "tracesQueryData": null, "spansQueryData": null, "parseMode": "Auto", "timeSource": "Message", "outputCardinalityLimit": 1000 } ], "description": "", "timeRange": null, "coloringRules": null, "linkedDashboards": [] }, { "id": null, "key": "panelPANE-FBE08549B2123A4A", "title": "Assets running OpenSSL", "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"series\":{},\"overrides\":[]}", "keepVisualSettingsConsistentWithParent": true, "panelType": "SumoSearchPanel", "queries": [ { "transient": false, "queryString": "_source=\"runZero Alerts\" and _collector=\"runZero\"\n| json field=_raw \"assets_new\" nodrop\n| toLong(assets_new)\n| json field=_raw \"found\" nodrop\n| json field=_raw \"search_url\" nodrop\n| json field=_raw \"rule_name\" nodrop\n| where rule_name = \"Assets with OpenSSL\" or rule_name = \"Assets with OpenSSL - Sumo\"\n| timeslice 1m\n| sum(found) by _timeslice\n| order by _timeslice", "queryType": "Logs", "queryKey": "A", "metricsQueryMode": null, "metricsQueryData": null, "tracesQueryData": null, "spansQueryData": null, "parseMode": "Auto", "timeSource": "Message", "outputCardinalityLimit": 1000 } ], "description": "", "timeRange": null, "coloringRules": null, "linkedDashboards": [] } ], "variables": [], "coloringRules": [] } ``` --- docs/tines.md --- title: Tines --- runZero integrates with ((Tines)) to help you automate workflows related to your asset data. This helps teams leverage runZero to the fullest while optimizing the team's workflows with automation. A [video demo](https://loom.com/share/ff57a5828b584442936b20ed622d51fe) is available to show the final outcome of these instructions. ## Requirements {#tines-requirements} * A Tines account * runZero Export API and Organization API tokens There are two ways to integrate runZero and Tines: * Follow the steps to create a [custom story in Tines](#tines-custom-story), or * Use the **[runZero sample story](#runzero-sample-story)** to begin with a story outline. ## Tines custom story A Tines story is a collection of actions that work together towards a specific goal, like a playbook. Tines has a Story Library that contains ready-made automated playbooks, or you can create a your own custom story if they don't have one that matches your needs. That's what we'll need to do here. ### Step 1: Creating a Tines story and adding runZero API credentials 1. After logging in to Tines, create a new story. 2. Use the `+` in the **credentials** section to add a [**text** credential](https://www.tines.com/docs/credentials/text). * **Name**: specify a name for the credential, for example `runzero_export_token`. * **Value**: your [runZero export API token](leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations) page. Export API tokens start with `ET`. 3. Use the `+` in the **credentials** section to add another [**text** credential](https://www.tines.com/docs/credentials/text). * **Name**: specify a name for the credential, for example `runzero_org_token`. * **Value**: your [runZero organization API token](leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations) page. Organization API tokens start with `OT`. ### Step 2: Creating a Tines webhook action 1. Add a **[Webhook](https://www.tines.com/docs/actions/types/webhook)** action to your story. 2. Click the **Webhook** action and copy the webhook URL, which will look like `https://.tines.com/webhook/`. ### Step 3: Creating a runZero alert template 1. Create an [alert template](https://console.runzero.com/alerts/template/create/) in runZero: * **Name**: name for template * **Template type**: JSON * **Subject line for message**: leave empty * **Body of message**: the following JSON example will include the rule name and the search URL in the alert message body: `{"rule_name":"{{rule.name}}","search_url":"{{search.url}}"}` 2. Create an [alert channel](https://console.runzero.com/alerts/channel/create/) in runZero: * **Name**: name for alert channel * **Channel type**: webhook * **Webhook URL**: the webhook URL you copied from Tines ### Step 4: Creating a rule in runZero Now that you have your template ready to go, you will want to identify which triggers to alert on. Some common examples are: * **Asset query results** - When there is a match on a query in runZero after a scan completes * **New assets found** - When a scan completes with new assets * **Agent offline** - When your runZero Explorer stops checking in to the console * **Task failed** - When a task fails for any reason We will use the **asset query results** selection for the rest of the steps. Our example will be any asset that has an open Telnet port `port:23`. You can [see more example queries](search-query-examples.md). 1. Create an [alert rule](https://console.runzero.com/alerts/rule/create/). 2. Select `asset-query-results` and click _Configure rule_. 3. Input values for the rule: * **Name**: name of the rule. * **Conditions**: optional parameters that will trigger the alert when all conditions match. * **Query**: query the assets must match, such as `port:23` for our example. * **Number of matches**: the numeric comparison logic for the **value**. * **Value**: the threshold of matches to trigger the rule. * **Limit to organization**: allows you to limit the alert to a specific organization in runZero * **Limit to site**: allows you to limit the alert to a specific site in runZero * **Action**: notify * **Notification channel**: name of the alert channel you created in step 2. * **Notification template**: name of the alert template you created in step 2. ### Step 5: Handling the data in Tines 1. The [**Webhook** action](https://www.tines.com/docs/actions/types/webhook) created in [Step 2](#step-2-creating-a-tines-webhook-action) will be the entry point for the runZero alert in Tines. 2. Add an [**Event Transform**](https://www.tines.com/docs/actions/types/event-transformation/extract) to parse the search from the URL provided in the runZero alert. If you connect the **Webhook** action to this one, some parameters will automatically populate. * Mode: extract * Matchers: * Path: `path_to_alert_search`, for example `receive_alerts_from_runzero.body.search_url` if your **Webhook** action is named "RECEIVE alerts from runZero" * Regex: `\?.*` * Extract to: `search` 3. Add an [Event Transform](https://www.tines.com/docs/actions/types/event-transformation/explode) that takes the output of the previous step. If you connect the previous **Event Transform** action with this one, some parameters will automatically populate. * Mode: explode * Matchers: * Path: `path_to_extraction_transform`, for example `get_search_from_url.search` if your previous **Event Transform** action is named "GET search from URL" * To: `individual_item` 4. Add an [HTTP Request](https://www.tines.com/docs/actions/types/http-request) to make an API call to the runZero Export API. * URL: the `path_to_explosion_transform` added to the end of the runZero API URL endpoint, for example `https://console.runZero.com/api/v1.0/export/org/assets.json<>` if your previous **Event Transform** action is named "GET search from regex" * Content Type: JSON * Method: get * Use the **+ Option** button to add **Headers**: * Change `header` to `Authorization` * Change `value` to `Bearer CREDENTIAL.runzero_export_token` 5. Add an [Event Transform](https://www.tines.com/docs/actions/types/event-transformation/explode) that takes the runZero Export API output and loops through each value. * Mode: explode * Path: `path_to_HTTP_request`, for example `get_assets_from_runzero.body` if your **HTTP Request** action is named "GET assets from runZero" * To: `individual_item` ### Step 6: Personalized automation in Tines Now that you have received the alert, parsed the search, and obtained the assets from the runZero Export API, it's time to add your own flare. While you will likely want to do something more crafty, the sample story provided includes these two actions as examples. 1. [Send an email](https://www.tines.com/docs/actions/types/email) to the destination of your choice for each asset. The sample JSON shows how you might customize it to put the context you'd like in the Subject and Body of the email. 2. The [HTTP Request](https://www.tines.com/docs/actions/types/http-request) action shows how you might reach back into runZero to add tags to the assets after other data is gathered. ## runZero sample story The [sample story below](#runzero-sample-story-json) can be imported to Tines to do all of the actions outlined in the steps above. Simply save a JSON file with the contents below, and use the **Import** button in Tines to upload it. After importing, you will need to complete the following steps. ### Step 1: Update credentials in Tines 1. Replace the `runzero_export_token` credential: * **Name**: specify a name for the credential, such as `runzero_export_token` * **Type**: text * **Value**: your [runZero export API token](leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations) page. Export API tokens start with `ET`. 2. Replace the `runzero_org_token` credential: * **Name**: specify a name for the credential, such as `runzero_org_token` * **Type**: text * **Value**: your [runZero organization API token](leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations) page. Organization API tokens start with `OT`. ### Step 2: Create runZero alert template 1. Create an [alert template](https://console.runzero.com/alerts/template/create/) in runZero: * **Name**: name for template * **Template type**: JSON * **Subject line for message**: leave empty * **Body of message**: the following JSON example will include the rule name and the search URL in the alert message body: `{"rule_name":"{{rule.name}}","search_url":"{{search.url}}"}` 2. Create an [alert channel](https://console.runzero.com/alerts/channel/create/) in runZero: * **Name**: name for alert channel * **Channel type**: webhook * **Webhook URL**: the webhook URL you copied from Tines ### Step 3: Create the rule in runZero Now that you have your template ready to go, you will want to identify which triggers to alert on. Some common examples are: * Asset query results: when there is a match on a query in runZero after a scan completes. * New assets found: when a scan completes with new assets. * Agent offline: when your runZero Explorer stops checking in to the console. * Task failed: when a task fails for any reason. We will use the **asset query results** selection for the rest of the steps. Our example will be any asset that has an open Telnet port `port:23`. You can [see more example queries](search-query-examples.md). 1. Create a [new alert rule](https://console.runzero.com/alerts/rule/create/). 2. Select `asset-query-results` and click `Configure rule`. 3. Input values for the rule: * **Name**: name of the rule. * **Conditions**: optional parameters that will trigger the alert when all conditions match. * **Query**: query the assets must match, such as `port:23` for our example. * **Number of matches**: the numeric comparison logic for the **value**. * **Value**: the threshold of matches to trigger the rule. * **Limit to organization**: allows you to limit the alert to a specific organization in runZero * **Limit to site**: allows you to limit the alert to a specific site in runZero * **Action**: notify * **Notification channel**: name of the alert channel you created in step 2. * **Notification template**: name of the alert template you created in step 2. ### runZero sample story JSON ```json { "schema_version": 4, "standard_lib_version": 6, "name": "runZero Sample Story", "description": null, "guid": "7706b502e51b4c68f0dbe9721c88d665", "slug": "runzero_sample_story", "exported_at": "2022-10-27T22:22:37Z", "agents": [ { "type": "Agents::WebhookAgent", "name": "RECEIVE alerts from runZero", "disabled": false, "guid": "ab1f5bf7be49c943d893ab993ade9421", "options": { "path": "da6e90c0b276bdda97e6bfa31ad50787", "secret": "5e290305e0a483bf843f1213f0f21dda", "verbs": "get,post" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null }, { "type": "Agents::HTTPRequestAgent", "name": "GET assets from runZero", "disabled": false, "guid": "d54d8f3f5b0ea857308f45f61a224547", "options": { "url": "https://console.runZero.com/api/v1.0/export/org/assets.json<>", "content_type": "application_json", "method": "get", "headers": { "Authorization": "Bearer <>" } }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": [] }, { "type": "Agents::EventTransformationAgent", "name": "GET search from URL", "disabled": false, "guid": "d62ddd189bb9080d778d900f2292504d", "options": { "mode": "extract", "matchers": [ { "path": "=receive_alerts_from_runzero.body.search_url", "regexp": "\\?.*", "to": "search" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": null }, { "type": "Agents::EventTransformationAgent", "name": "GET search from regex", "disabled": false, "guid": "41afc5c4d4c0fdb694d14e1eb380688a", "options": { "mode": "explode", "path": "=get_search_from_url.search", "to": "individual_item" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": null }, { "type": "Agents::EventTransformationAgent", "name": "LOOP through assets for follow up actions", "disabled": false, "guid": "b9ada61162bdf006f09d264845ebd304", "options": { "mode": "explode", "path": "=get_assets_from_runzero.body", "to": "individual_item" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": null }, { "type": "Agents::EmailAgent", "name": "SEND Email Action", "disabled": false, "guid": "0e9647b114f315d480f1f85c58e481d3", "options": { "recipients": "youremail@email.com", "reply_to": "youremail@email.com", "sender_name": "Your Name", "subject": "<>", "body": "Alert: <>\n\\
\n\\
\nLink to asset: https://console.runzero.com/inventory/<>\n\\
\n\\
\nAddresses: <>\n\\
\n\\
\nServices:\n<>" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": null }, { "type": "Agents::HTTPRequestAgent", "name": "TAG assets in runZero", "disabled": false, "guid": "c3171fed91ec40d39572260295a63ae0", "options": { "url": "https://console.runZero.com/api/v1.0/org/assets/<>/tags", "content_type": "application_json", "method": "patch", "headers": { "Authorization": "Bearer <>" }, "payload": { "tags": "hello=from_tines" } }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "width": null, "schedule": [] } ], "diagram_notes": [ { "content": "Hello! Thanks for importing the runZero Sample Story. \n\nThis story is a basic example of what you can do with runZero and Tines. \n\nPrerequisites:\n1. Create a text [credential](https://www.tines.com/docs/credentials/text) called `runzero_export_token`. Set the value as your [runZero export token](docs/leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations) page. Export tokens start with `ET`.\n2. Create a text [credential](https://www.tines.com/docs/credentials/text) called `runzero_org_token`. Set the value as your as your [organization API token](docs/leveraging-the-api.md), which can be obtained from the desired [runZero organization](https://console.runzero.com/organizations). Organization API tokens start with `OT`. \n\nThe steps are as follows:\n\n1. **RECEIVE alerts** provides the webhook destination for your runZero alerts \n\n2. **GET search from URL** parses out the search string from the URL provided in the runZero alert \n\n3. **GET search from regex** takes the list provided in step 2 and allows you to use the individual value \n\n4. **GET assets from runZero** uses the runZero Export API to get the list of assets related to the alert \n\n5. **LOOP through assets for follow up actions** takes the list of assets and sends each to the next steps individually \n\n6. **NOTE**: this is the step that you could implement more custom logic in most cases. All of the initial runZero and Tines data transfer is done, but it's your chance to customize this story to fit your use case. \n\n7. **SEND email action** simply sends an email to the destination of your choice \n\n8. **TAG assets in runZero** adds a tag in runZero to each asset showing an example of how you might reach back into runZero after doing other automated activities ", "position": [ 165.0, 180.0 ], "guid": "0e4b9b331dc65316849f7b089bf7bde2", "width": 375 } ], "links": [ { "source": 0, "receiver": 2 }, { "source": 1, "receiver": 4 }, { "source": 2, "receiver": 3 }, { "source": 3, "receiver": 1 }, { "source": 4, "receiver": 6 }, { "source": 4, "receiver": 5 } ], "diagram_layout": "{\"ab1f5bf7be49c943d893ab993ade9421\":[555,180],\"d54d8f3f5b0ea857308f45f61a224547\":[555,450],\"d62ddd189bb9080d778d900f2292504d\":[555,270],\"41afc5c4d4c0fdb694d14e1eb380688a\":[555,360],\"b9ada61162bdf006f09d264845ebd304\":[555,555],\"0e9647b114f315d480f1f85c58e481d3\":[555,690],\"c3171fed91ec40d39572260295a63ae0\":[780,690]}", "send_to_story_enabled": false, "entry_agent_guid": null, "exit_agent_guids": [], "exit_agent_guid": null, "keep_events_for": 604800, "reporting_status": true, "send_to_story_access": null, "send_to_stories": [], "form": null, "forms": [] } ``` --- docs/thinkst-canary.md --- title: Thinkst Canary aliases: ["/docs/set-up-thinkst/"] --- All runZero editions integrate with ((Thinkst Canary)) by providing quick access from the Canary console to your asset data in the runZero Console. Setting up the integration is as simple as one change to your Canary settings. ## Integrate runZero with Thinkst Canary 1. Sign in to your runZero console. 2. Sign in to your Canary console. 3. Go to **Global Settings** under the gear icon. 4. Click on **Integrations**. 5. Toggle the runZero switch. ## Accessing runZero data from Canary After the integration is enabled within the Canary settings, runZero data will be available through any incident. When viewing an incident, click the magnifying glass icon under `source IP` or `reverse IP lookup` to open a search in your runZero console. --- docs/exposure-management.md --- title: "Exposure management" --- runZero redefines exposure management with unrivaled visibility across your entire internal and external attack surface — covering IT, OT, IoT, mobile, and cloud. Uncover the unknown and unmanageable, reveal elusive exposures, and target the true risks other approaches miss. No agents, no authentication, no appliances. And most importantly, no blind spots. ## Comprehensive asset inventory runZero provides a comprehensive and unified asset inventory by combining [active scanning](discovering-assets.md), [passive traffic sampling](traffic-sampling.md), and [integrations](integrations-inbound.md) with deep fingerprinting and world-class correlation capabilities. Assets are normalized, deduplicated, and tracked as they move across your environment. ## Total attack surface management runZero offers comprehensive attack surface management for external, internal, cloud, IoT, and OT environments. ### External & Cloud runZero offers hosted scan engines for external monitoring. In addition to CIDRs, hostnames, and IPs, the runZero scan scope enables automatic target detection through specific keywords: - `domain:runzero.com`: This keyword will find all hosts associated with runZero.com and then scan both the IPb4 and IPv6 addresses of the results. - `asn4:1233`: This keyword will resolve all CIDRs associated with ASN 1233 and then scan these. - `country4:us`: This keyword can be used to scan entire countries, but more often it is used in the Excludes field to limit external discovery to a particular regions. - `defaults`: This keyword expands to all CIDRs and hostnames registered in the associated site. These keywords can be combined and used for both Scope and Exclusions. When the `Initialize` action is take in the scan page, a preview of the expanded targets is shown, along with an estimate of the scan time based on address count and full scope. Integrations are also used to identify and monitor the external attack surface. Assets imported from cloud providers like AWS, Azure, and GCP also include their external IPs and hostnames. ### Internal runZero enables comprehensive internal network attack surface enumeration using active scans, passive discovery, and integrations. The runZero scanner supports subnet sampling, which allows for incredibly fast discovery of massive internal ranges. Subnet sampling works by trickling packets into the most commonly used octets of each /24 and only scanning subnets where at least one reply was observed. This method also parses ICMP error messages to identify the network ranges used by the network equipment itself. runZero's `RFC1918` report can be used to identify blind spots and launch scans to close the gaps. In addition to scans, runZero can import PCAP files directly into the web interface, as well as turn any deployed Explorer into a passive network sensor. Passive discovery uses up to one CPU core of resources to parse all traffic passing through the interface, including broadcast, SPAN port data, and encapsulated traffic (VLAN, VXLAN, GRE, etc.). Lastly, runZero's extensive set of integrations makes it easy to determine what internal endpoints are missing a particular security control. For example, if you use CrowdStrike as your EDR, runZero can flag all Windows systems missing this agent. This also works for finding gaps in vulnerability management scopes. ### IoT & OT runZero was built for fast, unauthenticated, and safe scanning of all devices in all environments. This results in comprehensive coverage of internet of things (IoT) devices and reliable fingerprinting of operational technology (OT) equipment. runZero worked with the [US Department of Energy](https://www.runzero.com/blog/active-asset-discovery-ot-networks/) to ensure that our active discovery is safe and accurate for OT environments. Users who are unable to deploy active scanning can still take advantage of passive discovery, PCAP imports, and integrations with OT and IoT management tools. ### Inside-Out runZero also offers a unique capability called [Inside Out Attack Surface Management](https://www.runzero.com/blog/inside-out-attack-surface-management/) (IOASM). IOASM works by comparing the unique fingerprints of internal assets with a global database of public endpoints. This feature is enabled by default for customers using a runZero-hosted platform and is optionally available for self-hosted customers through additional configuration. IOASM can quickly tell you if an internal device is publicly exposed through an unexpected IP, including port forwards, VPNs, IPv6-tunnels, and more. Additional information can be found in this [presentation](https://www.youtube.com/watch?v=QyK_-elLjL8). IOASM reports four distinct vulnerabilities based on heuristics and detection type: - (TLS|SSH) Private Key is Public - (TLS|SSH) Private Key is Widely Shared - Potential External Access to Internal Asset (SSH, TLS) - Potential External Access to Internal Asset (MAC Address) The reported risk also varies based on heuristics. A publicly service attached to a Remote Desktop or Secure Shell system is considered higher risk than reuse of a public TLS key for a web application. IOASM also makes use of the [BadKeys](https://www.badkeys.info) compromised key database. ## Vulnerability detection {#em-vuln-detection} runZero identifies, imports, and manages vulnerabilities across your total attack surface using a combination of [query-based](em-queries.md) detection logic, [active scans](discovering-assets.md), and API-based [integrations](integrations-inbound.md) with leading endpoint management and vulnerability management platforms. Findings provide a comprehensive view of all detected security issues, misconfigurations, and other exposures across your assets. See [Findings](em-findings.md) for more details. runZero's [Rapid Response](em-rapid-response.md) program drives real-time detection and notification for zero-hour exposures. You can find the complete list of runZero-provided queries in the [Query Library](em-queries.md). Custom queries can created to report vulnerabilities on matching assets and services. Scan-based vulnerabilities are identified using an embedded version of [Nuclei](https://github.com/projectdiscovery/nuclei), the leading open source vulnerability scanner, in conjunction with [curated templates](em-templates.md) and runZero's best-in-class network discovery and fingerprinting engine. Vulnerability categories are configured as part of the scan configuration and specific templates are chosen dynamically by precisely matching assets and services. runZero recalculates vulnerabilities, findings, and asset risk as part of task processing. The resulting vulnerabilities and findings are shown in the respective product sections. ## Risk prioritization runZero normalizes and assigns risk scores to all assets. These scores are influenced by a combination of threat intelligence, vulnerability information, and exposure measurement. Asset criticality can be set through automated rules or manually through the product interface. Assets can be assigned to specific owners for remediation. Tags are imported from API integrations and can be managed natively within the interface, including rule-based tagging. Exported assets include the risk, criticality, and tag information set through the product interface. ## Continuous monitoring runZero continuously monitors your organization for changes to exposure, at a per-asset and per-service level. Recurring active scans, background passive traffic sampling, and regular sync with your existing infrastructure enable quick detection and reporting of new risks. Alerts can be managed in-product, sent by email, or delivered by webhook to the platform of your choice. All asset data can be synced to external platforms, including popular SIEMs and data lakes. --- docs/em-rapid-response.md --- title: "Rapid responses" --- runZero's Rapid Response program provides immediate detection and notification of emerging threats. Each Rapid Response includes a query to find matching assets, a trigger to analyze all inventories for exposure, and a corresponding blog post with the details of the issue. This program focuses on helping customers mitigate exposures before compromise. Vulnerabilities covered by the Rapid Response program are replaced by more specific coverage as mitigations become available. ## Latest Rapid Responses --- docs/em-queries.md --- title: "Query library" --- runZero includes a substantial library of pre-built queries. These queries can be used to detect vulnerabilities, trigger alerts, and apply changes to assets, such as tags and ownership. These queries are categorized by use case and risk level. Custom queries can also be configured to report vulnerabilities on matching assets and services. --- docs/em-templates.md --- title: "Vulnerability templates" lastmodexempt: true --- In addition to [query-based](em-queries.md) vulnerability reporting, runZero natively detects exposures using an embedded version of the open-source [Nuclei](https://github.com/projectdiscovery/nuclei) vulnerability scanner and it's YAML-based vulnerability check templates. To maintain fast scan times and minimize network disruption, runZero dynamically selects appropriate templates based on the scan's configured categories and precise asset and service fingerprinting. The table below lists the templates available for scans. The full set can be found in our [nuclei-templates](https://github.com/runZeroInc/nuclei-templates) repository. ## Current templates --- docs/em-findings.md --- title: Current Findings --- Findings are generated in three primary ways: 1. **Query-based**: These findings are identified through specific queries defined within the system (see list below). 2. **Nuclei-generated**: These findings result from scans where default credentials and vulnerability checks are enabled, leveraging Nuclei templates (see [templates](em-templates.md)). 3. **KEV (Known Exploited Vulnerabilities)**: These findings are triggered when a discovered vulnerability is present on the CISA Known Exploited Vulnerabilities (KEV) catalog or VulnCheck KEV. Below is a list of the current Finding codes and what searches generate them: --- docs/certificates-inventory.md --- title: "Certificates" --- runZero automatically collects TLS certificates as part active scans and passive network monitoring. These are stored in the Certificates Inventory, which you can access from the _Inventory_ menu, _Certificates_ sub-menu. Although the most sources of ((TLS certificates)) are web servers, certificates are also acquired from SMTP, RDP, and other TLS-aware services. Certificates have a validity period. In the inventory view, the _Valid from_ and _Valid until_ values are color coded to show if the certificate is not valid yet, has expired, or is soon to expire. A certificate has an _issuer_, the authority which signed the certificate. The issuer may be the same as the subject, in which case the certificate will be marked as self-signed certificate. Certificates rely on two kinds of algorithms: - The ((public key algorithm)), used for decryption and verification. - The ((signature algorithm)), used to produce a content hash that is signed using the public key algorithm. The security of a public key algorithm depends on the key size. This is shown in bits. How large a key is considered secure will depend on the algorithm. For example, for RSA a key size should be 2048 bits or larger to be considered secure; whereas for ed25519, all keys are 256 bits, and that's considered secure. The certificate inventory view has a button for each certificate to hide it from the inventory. This can be useful for embedded devices that have certificates you can't change, that you don't want to see in the inventory. If you later decide you want to see which certificates you've hidden, you can use the search query `hidden:true`. ## TLS certificates TLS certificates have three sets of names for their hosts: - The ((Subject)), an ((X.509)) ((distinguished name)) (((DN))) made up of one or more attributes, each with a value. - The ((Subject Alternative Name)) lists. These provide the values web browsers check against when connecting to a server. SANs are stored in a certificate in separate fields by type (DNS, IP, email or URI). - The ((Common Name)), which was once used by web browsers but is now ignored by them. It is typically in X.509 format. The Names shown in runZero for a TLS certificate are assembled from the four different kinds of SANs, plus the Subject DN. Each TLS certificate has a subject key ID used to identify the subject of the certificate, and an authority key ID used to identify the signing authority. These are used to link certificates together in a chain — the authority key ID of each certificate is the subject key ID of the next certificate in the chain. The issuer for a TLS certificate is included as a DN in the certificate. TLS certificates have a flag to say if they are intended for use as a ((certificate authority)) or (((CA))). The flag doesn't mean that they _are_ a CA, or that they are trusted; just that the certificate has that flag set. CA certificates are usually self-signed. The values shown to identify TLS certificate algorithms are mostly taken from RFC 5280, and should correspond closely to the values used by OpenSSL. The ((self-signed)) value indicates whether a certificate appears to be self-signed, based on its issuer, subject, and (if present) their IDs. A certificate may be flagged as apparently self-signed but not have a valid signature according to some software, as different software may implement more or less strict checks. The certificate details page has a button to download the certificate in PEM format. You can also download the entire chain of certificates known to runZero as a single PEM file. --- docs/reviewing-results.md --- title: "Reviewing results" --- ## Task details After each discovery task completes, the ((task details)) page will list a summary of how many assets were updated. To understand the numbers, it's important to remember that runZero will correlate assets across IPs and data sources, which can result in different results than IP-based matching alone. The change summary on the task details page includes the following statistics: * Asset changes: * **((Newly discovered assets))** are devices that were found during the task for which no device with matching fingerprints was previously seen. * **((Assets marked offline))** are assets that runZero has previously seen on the scanned network, but that didn't respond on any of the IP addresses during this scan. When this happens, the asset is marked offline. The offline status is a flag on the asset, and doesn't count as a change to the asset. Assets may be marked offline because the device was powered down or disconnected, or because of network problems. * **((Assets back online))** are assets that were marked offline at some point in the past, but the runZero Explorer got a response from them during this scan. The online status is a flag on the asset, and doesn't count as a change to the asset. * **((Assets changed))** is the number of assets where some property of the asset was modified, other than its online status. Examples include changes to the device's IP addresses or hostname, or responses from new ports or protocols. * **((Assets unchanged))** is the number of assets that were seen exactly where runZero found them in the last scan, with no changes to their responses. * **((Assets ignored))** is the number of occasions where the Explorer got a response from probing an IP address, but it turned out to be bogus in some way. This typically happens when a web proxy, stateful firewall, or SIP gateway responds as if it is the asset at every address on a subnet. * **((Total assets seen by task))** is the total of **Assets changed** plus **Assets unchanged**. It indicates the number of asset records that are now up-to-date. * User changes: * **((Newly discovered users))** are users that were seen for the first time during the integration sync. * **((Users changed))** are users that had attributes change during the integration sync. * **((Users unchanged))** are users that did not change during the integration sync. * **((Users updated by task))** is the total number of **Users changed** and **Users unchanged**, indicating how many user records are now up-to-date. * Group changes: * **((Newly discovered groups))** are groups that were seen for the first time during the integration sync. * **((Groups changed))** are groups that had attributes change during the integration sync. * **((Groups unchanged))** are groups that did not change during the integration sync. * **((Groups updated by task))** is the total number of **Groups changed** and **Groups unchanged**, indicating how many group records are now up-to-date. ## ((Dashboard)) & ((inventory views)) The dashboard will be populated with results after the first scan completes. The dashboard provides trend data and insights that will help you assess how your inventory is changing over time. You can select a time period and site for the trend data using the selectors at the top right of the dashboard page. The main asset trends graph shows the number of assets in each of the four main states -- live, offline, scanned and unscanned. Beneath the graph are additional asset breakdowns, each of which shows a top 10 of an asset category -- asset type, operating system, hardware and tags. The service trends graph shows how many total services were found in your asset inventory, along with breakdowns for ARP, ICMP, TCP and UDP. Below the service trends graph are breakdowns of the top 10 TCP ports, UDP ports, protocols and products detected. Clicking the menu button at the top right of each table and selecting "View more" shows a more detailed inventory by category. ## ((Insights)) from queries Queries and reports can help you gain valuable insights, but you may wonder where to get started. We recommend trying the pre-built queries in the [Query Library](https://console.runzero.com/queries/) first. Some of these queries are a result of runZero's [Rapid Response](https://www.runzero.com/categories/rapid-response/) to emerging threats and are described on our [blog](https://www.runzero.com/blog/). runZero's query language allows you to search and filter your asset inventory based on asset fields and value pairs. See the [documentation](docs/search-query-syntax.md) about querying your data. Once you are familiar with the query language you can write your own queries. You can set queries to run automatically by opening the query and setting the "Automatically track query results on the dashboard". The query will run when scans complete, and you will be notified of any resulting insights on the dashboard page. ### ((Sample Queries)) #### Asset inventory - Equipment that is likely 8+ years old: `alive:t mac_age:>8years` - Assets with end-of-life OS: `os_eol: Analysis reports are more advanced reports. They may run as tasks, rather than being generated on-the-fly. The first analysis report is [Compare Sites](site-comparison-report.md), which generates searchable reports of the differences between two sites. The Outlier Overview Report analyzes assets across the organization and summarizes the most unusual values for an assortment of key attributes such as hardware type and SNMP enterprise ID. The Specific Outlier Report allows you to select an attribute which has outlying values and get a detailed breakdown of those values. The Organization Overview Report builds a high level summary report of the entire organization. It can optionally include lists of assets found. ## ((Alerts)) As well as manually generated reports and queries, runZero also supports [automatic alerts](managing-alerts.md) to designated channels for post-scan inventory queries, asset changes, Explorer and scan issues, security operations, or API events. Available channels are internal notifications in the runZero web console, email, or webhooks that can enable integration with services such as Slack or Mattermost. Alerts use the same query language as the sample queries above, so this is a good way to automate proactive notification for critical events. --- docs/dashboard.md --- title: "Using dashboards" --- ((Dashboards)) provide customizable, visual views into your asset inventory and can be [created](#creating-dashboards) to serve different use cases such as compliance, vulnerability remediation, or asset visibility. A variety of visualization [widgets](#widget-types) are available that show operational information, trends, insights, goals, sources, and most and least seen graphs. You can also create your own [custom widget](#custom-widgets) based on queries to get the exact data you are looking to surface, displayed either as a trend line or latest count. You can filter the dashboard data by site and time buckets based on your needs by using the dropdown buttons at the top of the dashboard and selecting the timeframe and/or site you wish to filter by. You can also [customize](#customizing-dashboards) the arrangement and size of each widget on the dashboard to suit your particular needs using Edit Mode, and access the [widget library](#widget-library) to add or remove widgets as desired. ## Dashboard selection The dashboard selector button at the top of the dashboard displays the dashboard's name by default, and when clicked will open up a menu that displays runZero-managed dashboards, any shared dashboards, as well as your personal customized dashboards. To change dashboards, simply click the name of the dashboard you wish to view. ## Creating dashboards To create a new personal dashboard, click the dashboard selector and click the "Create new dashboard" button, which will create the new dashboard and automatically take you into Edit Mode where you can begin adding, resizing and arranging widgets. ## Customizing dashboards Personal dashboards can be customized by clicking the "Edit" button found in the dashboard header, which will put the dashboard into "Edit Mode" and allow resizing, rearranging, or adding and removing widgets. While in Edit Mode, each of the widgets on the dashboard can be resized according to your needs by clicking and dragging the bottom right corner of the widget. Widgets can also be rearranged within the dashboard by clicking and dragging on the widget heading area as indicated by the "cross-hair" mouse cursor icon. When satisfied with the configuration, save your customization settings by clicking the "Save" button so that you can quickly get to the information you'd like to see any time you visit the dashboard. If you wish to revert the dashboard to its original state, click the "Cancel" button to destroy your changes. This will reset the visibility, arrangement, and size of all widgets to reflect the current view of the dashboard prior to customizing it. ## Sharing dashboards A dashboard may be shared with any number of organizations by clicking the "Share" button. In the dialog, select the organizations to share the dashboard with and click "Done" to save the settings. When a dashboard has been shared with your organization by another user, the shared dashboard will appear under the "Shared with me" heading in the dashboard selector. Dashboards that you share with others will still appear within the "My dashboards" section, and can only be modified by you, but may be duplicated by other organization users if desired. ## Duplicating dashboards When viewing a runZero-managed dashboard or one shared with your organization, it cannot be modified directly, but you may make a copy of it to customize as desired by clicking the "Duplicate" button. Dashboards can also be duplicated by clicking the menu button at the top of the dashboard and selecting "Duplicate dashboard". In this case, a dialog will open that allows you to set the name of the new dashboard to distinguish it from the original version if desired. Note: sharing settings from the original dashboard will not be copied to the new dashboard. ## Default dashboards A user may choose to set any dashboard as their preferred dashboard by clicking the dashboard menu button and selecting "Set as my preferred dashboard". An organization admin can also set the default dashboard for all users of the selected organization by selecting the "Set dashboard as organization default" option. Within the dialog, select the "Override user-preferred dashboard" checkbox to override the user's preferred default dashboard if desired. When configured as such, users will only see their preferred dashboard if the organization doesn't have a default dashboard set to override their preference. ## Deleting dashboards A custom dashboard can be deleted by clicking the menu button at the top of the dashboard, selecting "Delete dashboard" and confirming the intention in the dialog that opens. This cannot be undone. ## Widget library The dashboard ((widget library)) is used to add and remove widgets on the dashboard, and can be accessed by clicking the "Widgets" button at the top right of the dashboard. When you open the widget library, a list of all the available widgets is presented for you to select from. You may also choose to create your own [custom widget](#custom-widgets) based on queries. Widgets included on the dashboard will be marked with a checkmark icon. When clicked, the widget will be deselected and removed from the dashboard when you click the "Save" button. Conversely, widgets that are not currently visible on the dashboard can be added by clicking on the widget to select it, and then saving the changes. ## Widget types ### Operational information - Live assets: number of assets currently alive based on the latest scans - Active scans: number of scans currently in progress - Explorers online: number of Explorers reporting as healthy - Accounts: number of users with access to your console ### Trends - Asset trends: timeline view of asset counts broken out by live, recent, and a couple other states - Service trends: timeline view of network services seen in your environment ### Insights - Latest ((insights)): automated queries that were ran after your latest scan with result counts ### Most and least seen graphs A variety of asset views by different asset properties. All of these graphs can be toggled between most and least seen based on the counts. - Asset types - Operating systems - Hardware - RRT latency - MAC vendors - Newest MAC age - TCP ports - UDP ports - Products - Protocols - Address count - Extra address count - Risk - Criticality - Tags ### Goals - Goals overview: summary view of all goals that are pinned to display on the dashboard ### Asset count and trend tables A view into the latest count and historical timeline for your assets related to ownership coverage, source types, and custom integrations. - Asset ownership: view of all ownership types including assets missing owners - Asset sources: view of all sources of asset data from supported integrations - Custom integrations: view of all custom sources of asset data from API integrations ### Bookmarks A customizable list of frequently visited pages, favorite reports, or external links. After adding the widget to your dashboard, you can manage the list by using the menu button at the top of the widget and selecting the appropriate menu item. Bookmarks can be edited or deleted by selecting the "Edit bookmarks" menu item, selecting the bookmark to be edited from the list shown in the dialog, updating the name or URL below, and saving the change. Similarly, a bookmark can be removed by clicking the trash can icon within the list if desired. Additional bookmarks can be added by selecting the "Add bookmark" menu item, entering a name and URL, and then saving the change. Bookmarks to external sites will open in a new window, while internal console URLs will open in the current window. When viewing individual reports or browsing the list of reports, you can easily add any report to your bookmarks by clicking the bookmark ribbon icon. After a report is bookmarked, you can remove it by clicking the ribbon icon again, which will open the editing dialog and allow you to remove the bookmark. ### Custom widgets Several widget types can be created and customized using the "Create widget" button in the widget library. These widgets fall into 4 types: - **Single match count** - Displays the most recent match count for a given query. - **Single match trend** - Displays a trend chart detailing the history of a given query. - **Multi-query match count** - Displays the most recent match count for 2 or more given queries, displayed similar to the _Organization overview_ widget. - **Multi-query trend line** - Displays a trend chart detailing the history of 2 or more given queries. - **Custom text widget** - Displays custom Markdown-formatted text content, which can be used to provide additional context or information on the dashboard. - **Goal progress overview** - Displays a summary and current progress towards completion for a single goal. Custom widgets can be customized in several ways. For single-query widgets, you can choose a name, query, and a color to style the results with. In the case of a multi-query widget, you can choose a name for the widget itself, and you can choose a name and color for each individual query as well. Any custom widgets that display as a trend chart can be exported to JPG, PNG, or SVG formats via the menu button in the top right of the widget on your dashboard. After creation, custom widget templates can be managed in the widget library by selecting the appropriate icon at the bottom of each widget's preview image. When updating a custom widget, you will be prompted to also update the widget on the dashboard if desired. Similarly, when deleting a custom widget, you will be prompted to also delete the widget from the dashboard if desired. ## Drill down Except for timeline-based charts, each widget's distinct data points can be viewed in detail by clicking on the relevant table row links or buttons, or by clicking on individual segments of donut, bar or column charts. ## Printing and exporting All chart-based widgets on the dashboard support exporting to SVG, PNG, and JPEG file formats, and table-based widgets can be exported to CSV format, by using the menu button at the top of the widget and selecting the file format you wish to export. The entire dashboard and all of its widgets can be printed by selecting the printer icon at the top of the dashboard. For best results, use a Chromium-based browser or Firefox with the 'Print backgrounds' option enabled to print the dashboard. ## Display mode The dashboard supports displaying in theater (or kiosk) mode, where navigation menus are hidden and only the dashboard content is shown. To enable theater mode, click the menu button at the top of the dashboard and select the "Enter theater mode" option. When theater mode is active, the dashboard also supports fullscreen display by clicking the _Fullscreen_ button at the top of the page. In order to exit fullscreen mode, press the `Escape` key or click the _Exit fullscreen_ button to return to theater mode. To exit theater mode, click the X icon to return to the normal browsing experience. --- docs/using-the-inventory.md --- title: "Using the inventory" --- The [inventory](https://console.runzero.com/inventory) page is the heart of runZero Network Discovery and the key to understanding what is on your network. The ((inventory)) displays all ((assets)) within the Organization and can be sorted, filtered, and exported to obtain specific views of the environment. ## Understanding assets An [asset](docs/understanding-assets.md) within runZero is defined as a unique network entity. Assets may have multiple ((IP addresses)) and ((MAC addresses)) and these addresses may change as the environment is updated. runZero tracks assets based on several heuristics, including MAC address, IP address, ((hostnames)), and ((fingerprint results)) for the ((operating system)) and running ((services)). In most cases, runZero can accurately follow assets over time in environments using ((DHCP)), even across remote ((subnets)). For external networks, scans that are initiated with fully qualified hostnames will consolidate assets based on the hostname, which allows for consistent asset tracking for cloud-based external systems with dynamic IP addresses. Within an organization, assets are isolated by ((site)), and each site can have address space that overlaps with other sites. Sorting the Inventory view based on the site column can help in these scenarios, as can filtering the Inventory based on a specific site name. The ((search)) field allows the inventory to be filtered based on the specified criteria. Please see the [search query syntax](docs/search-query-syntax.md) documentation for specific details. In addition to viewing assets, the Inventory page provides [data export](docs/exporting-asset-data.md) functionality, along with the ability to select assets, and specify the comments field. The _Rescan_ action can be used to selectively rescan specific systems from the inventory, while the _Remove Assets_ and _Purge Assets_ can be used to permanently remove data from the inventory view. The _Reports_ button provides quick access to key reports from the runZero [reports page](docs/reviewing-results.md#reports). ## Loading assets Data is loaded into the inventory using the **Scan** and **Import** buttons. The results are analyzed and merged, updating asset information as necessary. The **Scan** button has two options: Standard Scan and Full RFC 1918 Discovery. The latter is an easy way to set up a fast scan of all private range IP addresses. You can then use the [coverage reports](docs/coverage-reports.md) to check for assets in unexpected private address ranges. The **Import** button has two options. Importing runZero scan data allows you to import data. This means you can scan networks that have no connectivity to the internet, and still view the results in the runZero console. It's also useful for reprocessing old scan data so that you can use the [site compare](docs/site-comparison-report.md) feature to see how assets have changed over time. ### Bulk asset update The ((bulk asset update)) feature allows you to modify assets by [exporting a CSV](docs/exporting-asset-data.md) using the **Export** button, making changes to the data in a spreadsheet program or text editor, and then importing the result back into runZero with the **Import** button. This feature will update existing assets that have a matching `id` value in the organization. The fields listed below can be updated through the bulk asset update: * Type * Operating system * OS version * Hardware * Comments * Tags * Owner * Names * Domains The `type`, `os`, `os_version`, and `hardware` fields only accept a single value. The `comments`, `tags`, `owner`, `names`, and `domains` fields each accept multiple values, and a space-delimited list of `field=value` pairs is the standard syntax. The `tags` field can also be specified without `tag=` as just a space-delimited list of values. Only modifications to the `tags`, `comments`, and `owners` fields will be retained through subsequent scans, any changes to the other supported fields will be overwritten by the latest scan data. ## Connecting to other systems The **((Connect))** button lets you connect runZero to other systems. The [integrations](docs/integrations-inbound.md) you're able to connect depends on your license level, but may include tools like cloud and viritualization platforms, endpoint protection solutions, identity and access management tools, and vulnerability and risk platforms. These inbound integrations can also be configured as [scan probes](docs/integrations-inbound.md#integration-probe-connector) if required. ## Viewing ((services)) The Inventory page has a submenu labeled _Services_. This changes the table of data from an asset-focused view to a service-focused view. For each asset, you will see one row for each service runZero detected. Like the main asset view, the services view has a full search interface. You can filter services by protocol, port, and [many other criteria](search-query-services.md), using the [runZero search language](search-query-syntax.md). ## Viewing ((screenshots)) If the runZero Explorer has access to Google Chrome, it will attempt to take screenshots of web pages it finds while scanning your network. (This feature can be disabled in the scan options when setting up the scan.) You can view the screenshots for all of your assets via the _Screenshots_ submenu, and click through to the asset records for full details. ## Viewing ((software)) The inventory page has a submenu labeled _Software_. This flips the table of data from an asset-focused view to a software-focused view. For each asset, you will see one row for each software detected by runZero or a supported integration. Like the main asset view, the software view has a full search interface. You can filter software by vendor, product, and [many other criteria](search-query-software-groups.md), using the [runZero search language](search-query-syntax.md). ## Viewing ((vulnerabilities)) The inventory page has a submenu labeled _Vulnerabilities_. This flips the table of data from an asset-focused view to a vulnerability-focused view. For each asset, you will see one row for each vulnerability detected by a supported integration. Like the main asset view, the vulnerability view has a full search interface. You can filter vulnerabilities by CVSS score, name, CVE, and [many other criteria](search-query-vulnerabilities.md), using the [runZero search language](search-query-syntax.md). ## Viewing ((certificates)) The _Certificates_ submenu provides a searchable, sortable [certificates inventory](certificates-inventory.md) of all of the encryption certificates the runZero Explorer encountered while scanning. Like the other views, the certificates view has a search interface and can be sorted. ## Viewing ((wireless networks)) If the machine running the runZero Explorer has a working ((WiFi)) adapter and appropriate system tools installed, the Explorer will attempt to scan for nearby wireless networks. The _Wireless_ submenu will show the results of the scan. The tools required are: - Windows: `netsh.exe` (part of modern Windows releases) - macOS: Airport Utility - Linux: `iwlist`, often available via the `wireless-tools` package. ## Viewing ((users)) and ((groups)) The inventory pages for users and groups contain data imported from ((directory services)) such as Active Directory. The ((user directory)) and ((group directory)) can be populated using third party integrations listed under _Directory services_ in the _Integrate_ drop-down menu. --- docs/understanding-assets.md --- title: "Understanding assets" --- runZero treats ((assets)) as unique network entities from the perspective of the system running the Explorer. An asset may have multiple ((IP addresses)), ((MAC addresses)), and ((hostnames)) and it may move around the network as these attributes are updated. runZero tries hard to follow assets by correlating new scan data with the existing inventory, using multiple attributes. An asset is always associated with a single ((site)). If the same system happens to be covered by multiple sites, these will be treated as different assets, and will only be correlated against assets within their respective site. This separation by site allows the same network to be scanned from multiple perspectives and compared in a single view within the organization. After each scan, all assets within the corresponding site are updated. If a system is identified that doesn't match an existing asset, a new asset will be created. If an asset is part of the site and it is not found during a scan, it will be marked as ((offline)). If an asset is not correlated, due to substantial changes to the fingerprint (for example, a new network adapter was installed and the firewall was enabled), the previous asset will be marked as offline, and a new asset will be created to track the new configuration. This can lead to some level of duplication within a site, but these duplicates are usually marked as offline, and can be safely ignored or removed from the inventory by hand. ## Asset fields {#understanding-asset-fields} The following asset fields are available. ### Primary addresses runZero will report at least one and often multiple primary IP addresses for a given asset. These addresses can encompass multiple network interfaces but will only be displayed as a ((primary address)) if runZero has scanned it. This requires that the address is within the scan scope of one or more runZero scans. ### Secondary addresses runZero may report one or more ((secondary addresses)), based on network response probes. These are IP addresses that were detected on the asset but were not within the ((scan scope)). Secondary address detection is critical when trying to identify systems that bridge networks that should be isolated. ### Hostnames runZero may report one or more ((hostnames)). These names can be obtained from the initial ((DNS)) lookup (when hostnames are provided in the scan scope), from DNS PTR lookups during the scan, and by extracting names advertised within network probe responses. ### Operating System (OS) runZero attempts to fingerprint, and failing that, guess at the ((operating system)) running on each asset. If limited information is available, this field may be empty. ### Type {#understanding-type} runZero attempts to determine the general ((device type)) through analysis of fingerprints and running services. ### Hardware runZero attempts to determine the physical (or virtual) ((hardware)) if enough information is present. ### MAC addresses runZero may be able to enumerate one or more MAC addresses from the asset. MAC addresses are pulled from ((ARP)) if available, but also several network services that can return MAC address information across routed segments. ### Services runZero tries to detect approximately 100 ((TCP services)) by default, along with several useful ((UDP services)). These services are in addition to ARP and ((ICMP)). The services field contains a list of the most recently recorded services for the asset. ### Round Trip Time (((RTT))) runZero records the amount of time certain probes take in order to get a rough sense of the latency between the Explorer and the asset. ### ((Detected by)) runZero records which probe was used to identify an asset. For assets that are on remote subnets and have firewalls in place, this field indicates what service was used to obtain a response. ### ((Alive)) status runZero tracks whether a given asset was found during the most recent scan where its site was in scope. If the asset was not found, it will be marked as offline until a following scan detects it again. ### First seen runZero tracks the initial timestamp when an asset was first identified. ### Last seen runZero tracks the last timestamp when an asset responded to a probe during a scan. ### Outlier score runZero computes an ((outlier score)) for all assets in your inventory. The outlier score has a value from 0 to 5 (inclusive). It is a heuristic that aims to indicate how unusual the asset is, compared to all of the others in the inventory. Outlier scores are computed by examining key properties of the asset and its services, working out which values are unusual (infrequent) across the organization, and then computing how many unusual properties each asset has. The more unusual properties, the higher the asset's outlier score will be. --- docs/understanding-findings.md --- title: "Understanding findings" --- [((Findings))](https://console.runzero.com/findings) simplify ((vulnerabilities)), misconfigurations and best practices into a prioritized, curated and aggregated list that helps you identify and remediate the most critical risk in your environment. runZero Findings are available from the _Findings_ menu, and from the ((Risk Management)) dashboard. ## What are findings? Findings highlight the risks attackers are most likely to target. This enables security teams to focus remediation efforts on risks with real operational impact. Findings group similar vulnerabilities and misconfigurations together, providing a more holistic view of the risk they represent. Each finding contains a description of the risk, remediation steps, risk rankings, and an individual list of all assets and entities affected by the risk. ## Finding categories Each finding is placed into a category based on the type of risk it represents. Categories include: - ((Internet Exposure)): identifies assets and services that are potentially unintentionally exposed to the internet - Certificates: expired or soon-to-expire certificates as well as widely shared private keys - Vulnerability: actively exploited vulnerabilities or critical vulnerabilities that runZero believes are critical to address - ((End-of-Life)): operating systems, hardware and applications that have reached End-of-Life (EOL) or End-of-Service (EOS), and are no longer supported by the vendor - ((Open Access)): network services such as unauthenticated databases and sensitive applications that are accessible without authentication - ((Compliance)): assets and services that violate security best practices - Best Practice: general best practices that cover insecure authentication, service misconfiguration and obsolete protocols - ((Rapid Response)): emerging and novel threats covered in detail by runZero Rapid Response blog posts ## Findings list Findings can be found by using the main navigation menu directly below the Inventory item. They can be [searched](search-query-findings.md), sorted and exported similarly to other views within the console. ## Finding details When clicking on an individual finding's name to see its details, you will see an overview of the risks discovered, any associated external resources, and pertinent remediation information to help you address the risk. Below the finding summary, you will find a list of all the asset instances that the finding applies to, so that you can quickly prioritize remediation. ## How are Findings different from Vulnerabilities? A vulnerability is a specific security issue, usually closely tied to a specific CVE or security advisory. Vulnerabilities are found by the runZero Explorer or imported via one of the many supported integrations. There can be hundreds of thousands of vulnerabilities for any given asset, and even more across your entire environment. A finding is a curated, aggregated and prioritized list of risks that are most likely to be targeted by attackers. A single finding may group together several similar vulnerabilities. Findings are not always tied to a CVE and may include misconfigurations, best practices, and other security issues that may not make sense as a vulnerability. --- docs/asset-risk-and-criticality.md --- title: Asset risk and criticality --- runZero is able to help users assign and evaluate risk and criticality levels to the assets in their inventory. This can help prioritize risk mitigation or vulnerability remediation efforts by allowing users to quickly identify the assets in their organization with the highest levels of risk or criticality. ## Defining risk and criticality The **((risk))** level assigned automatically to assets in your inventory is inferred from the risk associated with vulnerabilities or risky configurations on that asset and defaults to the value `none`. Vulnerability risk level may be defined by the vulnerability management solution the vulnerability records are ingested from, or by the risk level assigned to a query vulnerability. The risk level can be overridden, in which case the override is retained until the asset or vulnerability is deleted. For vulnerabilities ingested from integrations, this may occur when the source no longer reports the vulnerability on that asset. The **((criticality))** level is assigned manually and defaults to the value `unset`. This value is intended to be used to denote the criticality or importance of an asset to your organization. As an example, you may choose to assign business-critical systems such as database and web servers a `critical` level, but normal enduser systems a `medium` level. ## Assigning asset risk and criticality Both asset risk and criticality can be assigned via the asset inventory. Asset criticality can also be assigned with alert rules. Superusers, administrators, and users can add or modify asset risk and criticality levels, and can reset risk assignment or remove criticality assignment from assets. ### Risk and criticality in the asset inventory Follow these steps to set risk and criticality through the asset inventory: 1. Select all the assets you wish to update, applying a query filter if needed. 2. Click the _Modify asset risk_ or _Modify asset criticality_ button to open the relevant popup. 3. Select the level of risk or criticality you wish to apply to the asset(s). 4. Click _Override risk_ or _Set criticality_ to apply your changes. ### Applying criticality with rules To automatically apply asset criticality values to assets after a scan, [create an alert rule](https://console.runzero.com/alerts/rule/create/) by going to **Alerts** > **Rules** and clicking the _Create rule_ button: 1. Select an inventory query you wish to use, such as the `asset-query-results` rule type, then click _Configure rule_. 2. Configure any desired settings. 3. Set the **Action** to _Modify asset_. 4. Select an option from the _Asset criticality_ menu. 5. Save the rule. This rule will now add the specified asset criticality level to all assets that match the rule when a scan completes. ## Asset risk report The **((Asset risk report))** provides visibility into the risk and criticality levels across your asset inventory. To run the Asset risk report, go to **Reports** > **Asset risk report** and click the **Asset risk report** button. Configure the following fields: 1. **Sites**: Select a site of assets to include in the report, or leave the default _All Sites_. 2. **Minimum risk**: Choose the minimum asset risk level to include. 3. **Minimum criticality**: Choose the minimum asset criticality to include. 4. **Top vulnerabilities per asset**: Set this field to an integer between 0 and 20. If the value is set to an integer between 1 and 20, the report will list up to that number of the top vulnerabilities detected on each asset. The top vulnerabilities are identified by sorting the vulnerability results for each asset by risk rank, then risk score, then severity rank, then severity score. 5. Click **Create report** to generate the results. The resulting report is grouped by asset criticality level and then sorted by risk level. The results can be exported as JSON Lines (.jsonl), a JSON document (.json), or CSV (.csv). --- docs/managing-ownership.md --- title: Managing ownership aliases: ["managing-asset-ownership"] --- runZero is able to help users track ((ownership)) with the ability to configure different types of owners and assign owners to runZero assets and vulnerability records. Ownership coverage can also be tracked as a [goal](docs/goal-tracking.md). ## Ownership types Superusers can manage the available types of ownership on the [**Account** > **Ownership types**](https://console.runzero.com/account/ownership-types) page. Custom ownership types can be configured to meet your needs. Some common ownership types may include **Security owner**, **IT owner**, or **Compliance owner**. The ownership type requires configuring three fields: * **Name**: the name of the ownership type. * **Reference**: whether the ownership type should be correlated with the user inventory, group inventory, or neither. * **Visibility**: whether the ownership type is visible through the asset inventory and asset details pages. The default `Asset Owner` ownership type, when visible, will be automatically populated with ownership-related data that runZero can glean from your configured integrations. The name of this ownership type can be changed by a superuser. The list of ownership types can be prioritized by dragging the types into the preferred order. This will dictate the order in which the types are displayed in the inventory and asset details pages. Only types marked `visible` will be displayed. ## Default asset owner Integrations populate the default asset ownership type. This is a prioritized mapping showing which traits from each integration would update that value. If an asset has more than one of these attributes, the first match in this table would populate. | Integration Source | Device/Object Type | Attribute Name | Reference Type | | :--- | :--- | :--- | :--- | | **Google Workspace** | Mobile | `owner` | User | | **LDAP** | Computer | `managedBy` | User | | **LDAP** | Computer | `manager` | User | | **Google Workspace** | ChromeOS | `orgUnitPath` | Group | | **Defender 365** | Device | `rbacGroupName` | Group | | **SentinelOne** | Device | `groupName` | Group | | **Google Workspace** | ChromeOS | `recentUsers.names` | User | | **Google Workspace** | Mobile | `email.names` | User | | **Google Workspace** | Endpoint | `email.names` | User | | **Miradore** | Device | `user.name` | User | | **Intune** | Device | `userDisplayName` | User | | **CrowdStrike** | Falcon Device | `email` | User | | **Google Workspace** | ChromeOS | `annotatedUser` | User | | **Google Workspace** | ChromeOS | `recentUsers` | User | | **Google Workspace** | Mobile | `email` | User | | **Google Workspace** | Endpoint | `email` | User | | **Miradore** | Device | `user.email` | User | | **Intune** | Device | `emailAddress` | User | | **Intune** | Device | `userPrincipalName` | User | | **SentinelOne** | Device | `lastLoggedInUserName`| User | ## Assigning owners to assets and vulnerabilities Once created, custom owners can be assigned via the inventory or through an alert rule. Superusers, administrators, and users can add or modify owner values, and can remove owners from assets or vulnerability records. Annotators can only add owner values, but cannot modify or remove owners. ### Ownership in the inventory Follow these steps to assign owners through the asset or vulnerability inventory: 1. Select all the assets or vulnerability records you wish to update, applying a query filter if needed. 2. Click the _Manage asset ownership_ or _Manage vulnerability ownership_ button to open the ownership popup. **Note**: Ownership values applied to an asset will be inherited by unowned vulnerability records on that asset. Vulnerability records with owners defined will not inherit the ownership value assigned to the asset. 3. Click _Add ownership type_ and choose which type(s) of owner you wish to apply to the selected assets or vulnerability records. 4. Add the owner value to the field. 5. Click _Save_ to apply your changes. ### Applying owners with rules To automatically apply ownership values to assets after a scan, [create an alert rule](https://console.runzero.com/alerts/rule/create) by going to **Alerts > Rules** and clicking the _Create rule_ button: 1. Select an inventory query you wish to use, such as the `asset-query-results` rule type, then click _Configure rule_. 2. Configure any desired settings. 3. Set the **Action** to _Modify asset_. 4. Specify a value for the _Set [ownership type]_ field for the ownership type(s) you wish to apply. **Note**: Ownership values applied to an asset will be inherited by unowned vulnerability records on that asset. Vulnerability records with owners defined will not inherit the ownership value assigned to the asset. 5. Save the rule. This rule will now add the specified owner type and value to all assets that match the rule when a scan completes. --- docs/managing-tasks.md --- title: "Managing tasks" --- You can view and manage discovery ((scans)) and other background actions from the [((Tasks overview page))](https://console.runzero.com/tasks). The _Active_ and _Completed_ task sections will show standard ((tasks)), such as scans and imports, along with their current progress and summarized results. You can [search or filter](docs/search-query-tasks.md) the tasks using different attributes. ## Task status values Tasks can have the following status values: * **New**: The task has been created and is waiting to be picked up by a scanner or connector. * **Active**: A scan task is in progress and the Explorer is scanning the network. * **Scanned**: The network scan part of a scan task has completed. * **Connecting**: A connector task is connecting to the remote system and downloading data. * **Connected**: A connector task has finished downloading and the data is waiting to be processed. * **Processing, queued**: Task data has been collected from a scan or a connector task, and is queued for processing. * **Processing**: Task data is being processed. * **Processed**: Task data has been processed and runZero data updated. * **Stopping**: The task was requested to stop and is in the process of doing so. * **Stopped**: The task successfully stopped. * **Canceled**: An error occurred which meant that the task could not continue. * **Paused**: A repeating task has been paused. ## Tabs Tabs on the Tasks overview page allow you to view a filtered subset of active, processing, scheduled, failed, completed, or recurring tasks. Each tab includes a search bar so that you can [search your complete task history](search-query-tasks.md). * **Active** shows all tasks currently scanning or connecting * **Processing** shows all tasks currently processing * **Scheduled** shows all non-recurring tasks that are scheduled to run * **Failed** includes all tasks that were unable to finish due to an error or cancellation * **Completed** lists all completed tasks in chronological order based on when the task finished processing * **Recurring** shows all recurring tasks ## Task details {#managing-tasks-details} Clicking on a task will open a card at the top of the page with details. The concentric circles show the progress of the task, with the outer circle tracking the scan or connection progress and the inner circle tracking the processing progress. The card also includes relevant timestamps and user creation data, as well as site, Explorer, and hosted zone settings. Completed tasks will also include the change summary, and recurring tasks will include a list of past runs. ## Scheduled tasks Scheduled tasks are one-off actions that will be started in the future, while recurring tasks are actions that happen on a regular basis. ((Recurring scan)) tasks generate a new standard task on each iteration of their schedule. Both scheduled and recurring scans will only launch if their associated Explorer is online and no other scan tasks are running. The Tasks page allows _Scheduled_ and _Recurring_ tasks to be removed and _Active_ tasks to be stopped. Please note that stopping an active _Scan_ task may take a few moments, as the status of the task is not updated until the Explorer confirms that the scan was terminated. ## System tasks runZero has system tasks that you may notice while searching through your tasks. Here are some examples you might see: * **Report-based**: a few reports will create tasks when initialized, including: * Organization overview report * Site and organization comparison * External assets report * **Outlier calculation**: this generates the outlier score seen in the asset details page and will show up with the name `Outlier calculation` * **Query**: all queries that are pinned to the Dashboard as Insights will show up with the name Query ## Dismissing failed tasks Tasks that were unable to finish due to an error or cancellation can be removed from the runZero Console by viewing the task details, clicking the "Dismiss" button and confirming the desired action. Dismissing failed tasks will archive the tasks so that they are no longer accessible. ## Reprocessing tasks You can use the Reprocess Tasks tool on the tasks overview to delete existing assets in the current organization and repopulate asset data from previous scan, import, and integration tasks using runZero's latest algorithms. This can potentially fix duplicated or incorrectly merged assets. To reprocess tasks: 1. On the Tasks Overview page, open the hamburger menu at the top right of the table and select "Reprocess tasks"; 1. Review the warnings in the modal that opens; 1. Enter a number of days to reprocess (this defaults to 7); 1. Enter the confirmation text; 1. Click "Continue". The process will take some time to delete the organization's assets and queue tasks that were created within the number of days specified for reprocessing. When it has finished queueing tasks, it will display the number of tasks to be reprocessed. You will then be able to monitor their progress in the console as normal. **Please note:** All assets in the organization will be deleted. Any tags, risk, criticality, comments, or other manually applied changes will be removed. During reprocessing, asset information may be incomplete and alert rules may be triggered. If your organization has a very large number of assets, it is possible for the request to time out before completing asset deletion. In this case, you can retry the request. The entire process may take several hours to complete. --- docs/goal-tracking.md --- title: Tracking goal progress --- With runZero goals, users are able to create and monitor progress toward achieving security initiatives. All goal types are supported by the robust query language on the backend. [All types of inventory queries](search-query-syntax.md) are supported by the ((goal tracking)) feature. There are two types of ((goals)): - **Saved query** - a goal based on the results of a user-defined or runZero system query against all inventory. - **Baseline** - a goal based on the results of a user-defined query against a subset of inventory, specified by another user-defined query. ## Goal creation New goals can be created by users whose [default role](managing-your-team.md) is user or greater from the [Goals](https://console.runzero.com/goals/) page in the console. Users with viewer-level or greater access will be able to view the goals page and see the goals that apply to organizations they have access to. To create a new goal, click the _[New goal](https://console.runzero.com/goals/new/)_ button on the _[Goals](https://console.runzero.com/goals/)_ page in the console. ## Creating saved query goals 1. On the _Goal type_ tab, select the **Saved query** type. 2. On the _Build goal_ tab, complete any desired fields: - **Name**: Provide a name for your goal. - **Description**: Provide a description for the goal. - **Notes**: Add relevant notes about this goal. - **Organization access**: By default, a goal will be created for the currently selected organization, but you may select additional organizations as desired. Goals are editable by any user with User role access to every organization associated with the goal, and can be read by any user with Viewer role access to at least one organization. - **Query**: Determine the query you want to use to track progress for this goal by selecting the query from the table. If needed, use the search field to find the query you wish to use. - **Threshold**: Select whether goal progress will be calculated as _Greater than or equal_ or _Less than or equal_, whether goal progress will be calculated as a percent or fixed number, and then set the desired threshold value. - **Target date**: Provide an optional target date for achieving this goal. 3. To see a preview of the goal's current state, click _Preview_. 4. Click _Save_ when you're ready, or make changes as needed. ## Creating baseline goals 1. On the _Goal type_ tab, select the **Baseline** type. 2. On the _Build goal_ tab, complete any desired fields: - **Name**: Provide a name for your goal. - **Description**: Provide a description for the goal. - **Notes**: Add relevant notes about this goal. - **Organization access**: By default, a goal will be created for the currently selected organization, but you may select additional organizations as desired. Goals are editable by any user with User role access to every organization associated with the goal, and can be read by any user with Viewer role access to at least one organization. - **Inventory dataset**: Select which inventory type should be searched by the target and baseline queries. - **Target query**: Compose the query for what the goal is targeting. The count this query returns becomes the numerator of the fraction representing the state of the goal, which the threshold is then compared to in order to determine goal progress. - **Target label**: Provide a label for the target query to appear in the goal breakdown. if a label is not provided, a default will be used. - **Baseline query**: Compose the query that defines the scope of the goal. The count this query returns becomes the denominator of the fraction representing the state of the goal, which the threshold is then compared to in order to determine goal progress. - **Baseline label**: Provide a label for the baseline query to appear in the goal breakdown. if a label is not provided, a default will be used. - **Threshold**: Select whether goal progress will be calculated as _Greater than or equal_ or _Less than or equal_, whether goal progress will be calculated as a percent or fixed number, and then set the desired threshold value. - **Target date**: Provide an optional target date for achieving this goal. 3. To see a preview of the goal's current state, click _Preview_. 4. Click _Save_ when you're ready, or make changes as needed. ## Goal progress calculation Once a goal has been created, the progress will be calculated once a day and when tasks complete. As a result, you may see a different number of metric calculations in the historical line chart depending on the number of tasks that are completed on a given day. The _overall status_ noted in the _Goal details_ card on a goal details page reflects the progress toward goal completion for all the configured organizations that you have access to. This may differ for a user with more or less per-organization access. **Note**: When a goal applies to multiple organizations, progress is calculated per-organization and extrapolated across all applicable organizations. ## Goal events and notifications The events system includes the following events related to goals: - `goal-created`: This event fires when a goal is created and saved. - `goal-updated`: This event fires when a goal is modified and saved. - `goal-completed`: This event fires when the progress of a goal crosses the completion threshold. - `goal-lapsed`: This event fires when the progress for a previously completed goal falls below the completion threshold. - `goal-removed`: This event fires when a goal is deleted. These events can be used with [channels](managing-alerts.md) and [rules](rules-engine.md) to receive notifications about a change in goal status. After a [notification channel](https://console.runzero.com/alerts/channels/) has been created, [create a rule](https://console.runzero.com/alerts/rules/) for the desired event and select the channel you wish to receive the notification through. --- docs/understanding-suppression.md --- title: Understanding suppression aliases: ["/docs/understanding-suppression/"] --- runZero supports ((suppressing)) records for findings, vulnerabilities and vulnerability groups so that they are not shown in the platform if desired. This can be useful for filtering out false positives for example, or hiding any vulnerabilities that are not relevant to your environment for some reason. Suppressed objects are not deleted, but remain stored within the platform with metadata about when and why they were suppressed, and by whom. ## How suppression works {#understanding-suppression} ((Suppression)) works differently depending on the type of object being suppressed. When a vulnerability instance is suppressed, it becomes hidden from view on the vulnerabilities by asset inventory. When a finding is suppressed, it becomes hidden from view on the findings list, and any vulnerabilities associated with the finding will also be suppressed. Similarly, when a vulnerability group is suppressed, it becomes hidden from view on the vulnerability groups inventory, and any vulnerabilities associated with the group will also be suppressed. When a vulnerability, finding, or vulnerability group is suppressed, it will not be considered when displaying an associated asset's risk score or be included in dashboard metrics data from that point forward. **Note:** when vulnerability groups or findings are suppressed, and new associated vulnerability instances are found by future scans, those new vulnerabilities will also be suppressed automatically. If all existing vulnerability instances associated with a finding or vulnerability group are suppressed, but the finding or vulnerability group itself is not suppressed, then the finding or vulnerability group will still be shown in the platform, but it will show a count of zero associated vulnerabilities until new associated vulnerability instances are detected by future scans. ## Suppressing and unsuppressing objects {#suppressing-unsuppressing} Vulnerabilities, findings, and vulnerability groups can be suppressed or unsuppressed from multiple locations within the runZero platform. Individual findings and vulnerabilities can be suppressed from their respective detail pages using the "Suppress" button found in the page header, and bulk actions can be performed from data grid views such as the vulnerability inventory by asset, vulnerability groups inventory, or findings list. When choosing to ((suppress)) an object, a modal will appear, asking for a reason and an optional comment. Select the most appropriate reason from the dropdown menu, or select "Other" to provide a custom reason in the comment box. Click the "Suppress" button to confirm the desired action, and if successful, the modal will then close and the object will be marked as suppressed. When a finding or vulnerability is suppressed, a banner appears at the top of its detail page, and suppression can be removed by clicking the "Remove suppression" button and confirming your intent. When using a data grid view such as the vulnerability inventory by asset, vulnerability groups inventory, or findings list, multiple rows can be selected using the checkboxes in each row, and then by clicking the "Modify" button and selecting either the "Suppress" or "Remove suppression" option from the dropdown menu. This can be used to quickly suppress or remove suppression from many objects at once. Action buttons within each row can also be used to quickly suppress or unsuppress individual rows. ## Searching for suppressed objects {#suppression-search} When using the vulnerability inventory by asset, vulnerability groups inventory or findings list, a boolean search query `suppressed` can be used to filter for suppressed or unsuppressed items. For example, to find all suppressed items, use the following query: `suppressed:true`. To display both suppressed and unsuppressed items, a query of `suppressed:any` can be used. Additionally, each data grid view has a "Suppression" quick filter button with menu that can be used to toggle the view between showing all items regardless of suppression state, only suppressed items, or only unsuppressed items. ## Dashboard widget {#dashboard-widget} The "Suppression overview" dashboard widget provides a count for suppressed findings, vulnerabilities, and vulnerability groups at a glance, and can be added to any custom dashboard via the [widget library](dashboard.md#widget-library) modal. ## Suppression events {#suppression-events} A number of runZero system events are triggered when suppression actions are taken. These events can be used to power rules within the [rules engine](rules-engine.md) that take action when suppression events occur. The following events are used for suppression actions: - `vulnerabilities-suppressed`: fires when a vulnerability is suppressed. - `vulnerabilities-unsuppressed`: fires when a vulnerability's suppression is removed. - `findings-suppressed`: fires when a finding is suppressed. - `findings-unsuppressed`: fires when a finding's suppression is removed. - `vulnerability-groups-suppressed`: fires when a vulnerability group is suppressed. - `vulnerability-groups-unsuppressed`: fires when a vulnerability group's suppression is removed --- docs/understanding-network-segmentation.md --- title: "Understanding network segmentation" --- ## runZero multi-homed asset detection ((Network segmentation|network segmentation)) is a critical security control for many businesses, but verifying that ((segmentation)) is working correctly can be challenging, especially across large and complex environments. Common techniques to validate segmentation, such as reviewing firewall rules and spot testing from individual systems can only go so far, and comprehensive testing, such as running full network scans from every segment to every segment, can be time intensive and are hard to justify on a regular basis. For businesses subject to the ((PCI DSS)) requirements, validating cardholder data environment (((CDE))) segmentation is an important part of the security audit process. The [PCI guidance on scoping and segmentation](https://www.pcisecuritystandards.org/documents/Guidance-PCI-DSS-Scoping-and-Segmentation_v1.pdf) describes a common CDE administration model. The network bridge detection in runZero is opportunistic and far from perfect, but it may highlight areas where segmentation is broken, and can cut down on the number of surprises encountered in a future security audit. ## Using the bridge report The ((bridge report)) shows external networks in red and internal networks in green. This view is not a typical network map, but instead shows possible paths that can be taken through the network by traversing multi-homed assets. Assets where runZero only detected a single IP address are not shown in order to keep the graph readable. Zooming in will show asset and subnet details. Clicking a bridged node once will highlight the networks it is connected to, and clicking it a second time will either take you to the asset page. Clicking a network once will highlight the connections to bridged nodes, and clicking a second time will perform a CIDR-based inventory search. Bridge detection is useful when validating network segmentation and ensuring that an attacker can't reach a sensitive network from an untrusted network or asset. Examples of this include laptops plugged into the internal corporate network that are also connected to a guest wireless segment and systems connected to an untrusted network, such as a coffee shop's wireless network that also have an active VPN connection to the corporate network. runZero detects network bridges by looking for extra IP addresses in responses to common network probes (NetBIOS, SNMP, MDNS, UPnP, and others) and only reports bridges when there is at least one asset identified with multiple IP addresses. Typical hardening steps, such as desktop firewalls and disabled network services will usually prevent multi-homed assets from being detected by runZero. The screenshot below shows how to search for multi-homed assets in the runZero inventory. ## Using the asset route pathing report Network segmentation is a foundational security control that can be easily undermined by network misconfigurations and multi-homed machines. runZero Platform users can now visualize potential network paths between any two assets in an organization using the ((asset route pathing)) report. This report generates a graph of multiple potential paths by analyzing IPv4 and IPv6 traceroute data in combination with subnet analysis of detected multi-homed assets–without requiring access to the hosts or network equipment. This unique methodology identifies surprising and unexpected paths between assets that may not be accounted for by existing security controls or reviews. With a view of potential paths, security professionals can verify whether a low-trust asset, such as a machine on a wireless guest network, can reach a high-value target, such as a database server within a cardholder data environment (CDE). The new feature highlights potential network segmentation violations and opportunities for an attacker to move laterally from one segment to another. --- docs/fingerprinting.md --- title: Understanding fingerprints aliases: ["/docs/fingerprints/"] --- runZero automatically builds **fingerprints** for every asset it discovers. Fingerprints describe how runZero identified a device, service, or operating system based on collected evidence. Each fingerprint includes a set of attributes that show *what was matched* and *where it came from*. Fingerprints are a core part of how runZero normalizes your inventory, enabling accurate correlation and deduplication across multiple discovery sources. ## How fingerprints work {#understanding-fingerprints} During discovery, runZero gathers a variety of clues—such as TCP banners, mDNS names, SMB negotiation data, TLS certificates, and more. Each clue is analyzed and classified into one or more fingerprint categories. Fingerprints are stored within the asset record using keys that follow the pattern: ``` fp.. ``` For example: * `fp.os.source` — identifies which source provided the operating system fingerprint * `fp.os.match` — shows the string or probe result matched to identify the OS * `fp.hw.vendor` — lists the hardware vendor name These values are visible in exports, the API, and internal datasets. ## Refingerprinting and submitting improvements {#fingerprint-improvements} If a fingerprint appears incorrect or incomplete, you can: * **Refingerprint the asset** — re-run the fingerprinting process for that specific asset using the latest detection logic. This can update OS, hardware, and type fields. * **Submit a fingerprint improvement** — provide feedback to help enhance fingerprinting accuracy. When submitting an improvement, you can specify: * **Type** (e.g., *Server*, *Router*) * **Operating System** (e.g., *Windows 10*, *Ubuntu 22.04*) * **Hardware** (e.g., *VMware VM*, *Synology NAS*) * Optional **comments** for additional context. These improvements help refine fingerprinting logic in future releases and improve identification accuracy for similar devices. ## Fingerprint categories {#fingerprint-categories} Each fingerprint category corresponds to a logical area of asset identification. Common categories include: | Category | Description | Example sources | |-----------|--------------------------------------------------|--------------------------------| | `os` | Vendor, operating system, and version detected | TCP banners, SMB, mDNS | | `hw` | Hardware and vendor identification | SNMP, MAC lookup, integrations | | `type` | Asset type classification | runZero service probe | ## Common fingerprint attributes {#fingerprint-attributes} The table below lists fingerprint attributes observed in exports and the API. | **Attribute** | **Meaning** | **Sample Values** | | -------------------- | --------------------------------------------- | -------------------------------------------------------- | | `fp.build` | Internal fingerprinting engine build version | `v4.0.251103.0-2fd02762da549a3e87ffb5b0649e1621011872dd` | | `fp.hw.certainty` | Confidence level of hardware fingerprint | `0.8`, `1.0` | | `fp.hw.cpe23` | CPE 2.3 identifier for the hardware | `cpe:2.3:h:dell:optiplex_7080:-:*:*:*:*:*:*:*` | | `fp.hw.device` | Detected hardware device type | `Laptop`, `Server`, `Switch` | | `fp.hw.match` | Raw hardware identification string | `Dell Inc. OptiPlex 7080`, `HP ProLiant DL360` | | `fp.hw.product` | Hardware product name | `OptiPlex 7080`, `ProLiant DL360`, `MacBookPro18,3` | | `fp.hw.serialNumber` | Serial number extracted from hardware probe | `ABC123XYZ`, `VMware-564d4a4a` | | `fp.hw.source` | Source that provided the hardware fingerprint | `SNMP`, `Intune`, `CrowdStrike`, `runZero` | | `fp.hw.vendor` | Vendor identified from hardware data | `Dell`, `HP`, `Apple`, `Lenovo` | | `fp.hw.version` | Hardware or firmware version string | `1.0.3`, `rev A00` | | `fp.os.build` | OS build number parsed from source data | `22621`, `19045`, `22D68` | | `fp.os.certainty` | Confidence level of OS fingerprint | `0.95`, `1.0` | | `fp.os.cpe23` | CPE 2.3 identifier for the operating system | `cpe:2.3:o:microsoft:windows_10:19045:*:*:*:*:*:*:*` | | `fp.os.device` | Detected OS device type | `Desktop`, `Server`, `Mobile` | | `fp.os.edition` | OS edition or variant | `Pro`, `Enterprise`, `Home` | | `fp.os.match` | String matched to infer the OS | `Windows 10.0`, `Ubuntu 22.04`, `macOS 14.1` | | `fp.os.product` | OS product name | `Windows 10`, `Ubuntu`, `macOS` | | `fp.os.source` | Source that provided OS identification | `runZero`, `MDNS`, `Intune`, `AzureAD` | | `fp.os.vendor` | Vendor identified from OS data | `Microsoft`, `Canonical`, `Apple` | | `fp.os.version` | OS version parsed from matched data | `10.0.19045`, `22.04`, `14.1` | | `fp.type.source` | Source that provided type classification | `runZero`, `Integration`, `Hostname`, `AzureAD` | ## Using fingerprints in queries {#fingerprint-queries} During asset processing, these `fp.x.y` values are normalized to `os`, `os_version`, `hw`, and `type` attributes. These are some sample searches using the normalized attributes: * Windows `os` assets ``` os:windows ``` * Ubuntu assets running `os_version` less than 20.04 ``` os_version:<20.04 os:ubuntu ``` * Assets with Dell `hardware` ``` hw:dell ``` * Assets with the `type` server ``` type:server ``` ## Troubleshooting fingerprints {#fingerprint-troubleshooting} If a fingerprint appears incorrect or incomplete: 1. Check which `fp.*.source` values contributed to the identification. Multiple integrations or probes may overlap. 2. Review recent discovery runs to confirm whether an updated probe result is available. 3. Consider enriching with integration data sources (e.g., Intune, CrowdStrike) to improve fingerprint accuracy. By understanding and using fingerprint data, you can verify discovery accuracy, correlate results across integrations, and build more precise asset views within runZero. --- docs/managing-alerts.md --- title: "Managing alerts" --- runZero can trigger automatic ((alerts)) when certain events occur through a combination of ((Channels)) and ((Rules)). runZero currently supports Internal, ((Email)), ((Email runZero Users)), and ((Webhook)) channel types. Internal channels store events within the [Alerts](https://console.runzero.com/alerts) list within the runZero Console. Internal alerts support explicit acknowledgement. Internal alerts can be bulk acknowledged and cleared from within the runZero Console. Email channels can be configured to deliver mail to one or more recipients. These email messages contain a summary of the alert and a link to the specifics within the runZero Console. Email is sent from the runZero infrastructure using the ((Sendgrid)) service. Webhook channels allow runZero to post alerts to internet-reachable web services. The post request contains a standard text message for use with platforms like ((Slack)) and ((Mattermost)), but also additional fields containing the full alert details. Webhooks are a great way to tie runZero alerts into third-party platforms. To trigger an alert on a channel, a [Rule](https://console.runzero.com/alerts/rule/create/) must be created. Rules define which events lead to alert on which channels. The name of the rule will be included in the alert content and should describe the type of event that it monitors. The following are some example event types that can be used to create rules: * Scan completed * New assets found * Assets back online * Assets now offline * Assets changed _Scan completion_ and _assets changed_ rules can be noisy but may be useful to keep a running log of network changes over time. For a typical monitoring use case, a rule would be created to trigger on _Assets now offline_, _Assets back online_, and _New assets found_, automatically alerting an email alias or a Slack channel. Alert rules, when combined with recurring scans, can be a simple way to track network changes over time. --- docs/rules-engine.md --- title: Using the rules engine aliases: [ "/docs/event-based-rules/" ] --- The ((Rules)) Engine is an automation framework for monitoring, alerts, and workflow management. You can use the Rules Engine to customize ((alerts)) for the ((events)) that matter most to your organization and automate repetitive tasks. At the heart of the Rule Engine are rules. A rule defines the action that is taken based on a set of conditions. You can create rules to proactively alert your team when there are changes to things like Explorers, assets, scans, organizations, and sites. You can also automate tagging and modification of asset fields based on the results of a query. Some ways you can use the Rules Engine to help automate your workflow: - Alert your team when new policy violations are identified. - Modify asset fields when the assets match specific criteria. - Bulk tag assets that match a specific query. - Get a Slack notification when a query returns new results. - Monitor when an Explorer goes offline in the runZero console. - Know when there are changes to organizations, sites, and users. ## Key concepts Rules can help you stay on top of events as they happen and get better visibility across your network, assets, and your runZero deployment. To build a rule, you need to define four things: events, organization access, conditions, and actions. A rule determines that when a specific event happens, and certain conditions are met, the system will automatically perform the configured action. ### Events Each rule begins with an event. The event sets off the trigger and puts your rule into motion. An event can be based on a query or a system-defined event. runZero offers a library of system-defined events you can use to create your rules. Choosing any of these events will show the conditions and actions available. ### Organization access Each rule can be used by any number of organizations. Rules are editable by any user with User role access to every organization associated with the rule, and can be read by any user with Viewer role access to at least one organization. By default, a rule will be triggered for the currently selected organization. Setting organizational access on templates and channels only specifies who can view and edit, not which rules can use them. You can set up a rule for an organization with a template and/or channel whose access does not include that organization, as long as you have at least Viewer role access to one or more organizations in the template or channel's organization access list. ### Conditions A condition narrows the scope of your rule. Unless the condition is met, the rule will not execute the action. You will only see conditions that apply for the event you have chosen. Generally, conditions specify sites, organizations, and asset attributes for the event. ### Actions An ((action)) executes your rule, if the event occurs, and the conditions meet all the criteria. An action can be a notification to a channel, or it can be a modification to an asset. What you will need to configure depends on the action type. For notifications, you'll need to specify the notification channel and template. For asset modification, you can edit fields like the OS vendor, OS product, OS version, hardware vendor, hardware product, hardware version, asset tags, and asset type. ### Channels {#rules-channels} A ((channel)) provides a way for you to communicate when a specific event has occurred. You can create multiple channels to support different types of communication needs. For example, you may want to create a Slack channel for one team, and an email list for another. It depends on what communication channels you prefer, and who you are trying to reach. Much like rules, channels can also be utilized by any number of organizations, and managed by any user with User role access to all associated organizations. Similarly, any user with Viewer role access to one or more organizations will be able to view the channel details only, and may not edit or create new channels. The body of the message uses default text from runZero. Customizations for messaging is currently unavailable. ## Create a rule Rules set the criteria for actions to take place. To create a rule, you need to choose an event, define the conditions, and choose a resulting action. ### Step 1: Open the Rules Engine - From the Alerts menu, select the Rules submenu. - Click **Create Rule** to open the editor. ### Step 2: Choose an event type and configure organization access - Provide a descriptive name for the rule. Something that quickly that tells you what the rule does. - Choose an event you want to use as your trigger. - You can browse the list of available predefined events. Use the left-hand categories to narrow down the list, or the search field to quickly filter by keyword. - Choosing 'asset-query-results' or 'service-query-results' will allow you to modify the fields for the resulting assets. - After you've chosen an event and configured organization access, click **Next**. ### Step 3: Define the conditions - The conditions you can configure depend on the event you have selected. - If you have an asset or service based query selected, you'll need to [provide a query](search-query-syntax.md) for the rule. This query will run against the site after the scan completes. Note that assets with data from non-runZero sources must be recent (seen in the last 30 days) to be included in the scope of the search, and runZero-scanned assets must be live. - You may also set the scope to a specific site or Explorer, and sometimes, depending on the event, minimum asset counts or task type. ### Step 4: Choose an action, and optionally select a specific channel or template - Actions can execute a notification to the channel of your choice or modify assets. For example, you can choose to send notifications via email when orphaned devices are found. ### Step 5: Turn on and save the rule - Turn the rule on if you want to activate it immediately by selecting the "Enable this rule" checkbox. Otherwise, you can save the rule and turn it on later. - Save the rule when you're done. ## Keep in mind Using scan and asset event types can be noisy, but they are useful for tracking network changes over time. To help you focus on the events that matter most, track assets that go offline, assets that come back online, and newly discovered assets. ## Monitoring the status of rules The ((rules submenu)) of the Alerts page displays a list of all rules that have been created. For each rule, you can see: - Whether the rule is enabled. - The event that triggers processing of the rule. - The organizations the rule applies to, if the rule has been limited to specific organizations. - When the rule was last triggered. - Whether the rule resulted in an action being processed or not. - When the rule was created and the username that created it. A status of "skipped" means that last time the rule was processed, its preconditions weren't met, so no action was taken. A status of "processed" means that the rule's preconditions were met, and its action has been processed. If there is an error processing a rule or sending a notification, the action status of the rule will be set to "error". The error message can be seen as a tooltip on the error status. --- docs/creating-alert-templates.md --- title: Creating alert templates h2Styled: false description: "How to create templates for your alerts" --- With the [Rules Engine](rules-engine.md), you can define ((rules)) that alert you on specific events, such as changes to scans, assets, and Explorers. To customize the ((alert messages)), you can create custom ((templates)) to standardize and format alerts triggered from rules. With custom templates, you can include more context and data for your alerts. Templates can output as raw HTML, a runZero HTML template, JSON, and text for use in emails, internal notifications, or ((webhooks)). You can customize the contents of these templates as needed. Like rules and channels, templates can also be utilized by any number of organizations, and managed by any user with User role access to all associated organizations. Similarly, any user with Viewer role access to one or more organizations will be able to view the template details only, and may not edit or create new templates. ## Template building basics You can define the contents of an alert message using the [Mustache](https://mustache.github.io/) templating language. As long as you know a little bit about how the [Mustache syntax](http://mustache.github.io/mustache.5.html) works, you can build custom HTML and JSON templates to reference and pull in runZero data. - For ((Slack)) notifications, you can use Slack's [((Block Kit))](https://api.slack.com/block-kit) and their interactive [Block Kit Builder](https://app.slack.com/block-kit-builder/) to construct a rich message in JSON format, and then use Mustache to insert the relevant data. - For ((Microsoft Teams)), you can use the [((Adaptive Cards))](https://adaptivecards.io/samples/) format to build rich messages, and again insert data via Mustache. Our templates have two fields for template data: subject and body. Both subject and body can be customized using the ((Mustache)) syntax. ### Inserting a data in a template A standard set of objects is passed to the {{template engine}}, you just have to indicate the fields from the objects you want to insert into your template. Use the Mustache template syntax, `{{variable}}`, to include alert values when a rule matches certain conditions. For HTML and JSON templates, values inserted using `{{ }}` are automatically escaped according to the appropriate rules. To avoid escaping a particular value, use triple curly braces, like this: `{{{task.name}}}`. For JSON templates, the special self variable `{{.}}` at the top level will output all available variables and their values as JSON. #### Special rules for JSON For JSON templates, variables are rendered differently depending on whether they are single values or multiple values: - A string or number gets rendered to the raw value. A string will have any embedded quotes escaped, but it won't be wrapped in quotes. This is so you can put multiple strings or numbers into a single JSON string in your template. - An object or array gets rendered to the full JSON representation of the object or array. This is for convenience, so that you can dump arrays and objects to JSON without having to loop through values. However, it means that if you try to put an array value into a JSON string by surrounding it with quotes, the result won't be valid JSON. Consider the following template running on an asset with multiple IP addresses: ``` { "addresses_1": {{addresses}}, "addresses_2": "{{#addresses}}{{.}} {{/addresses}}", "addresses_3": "{{addresses}}" } ``` Here's the result: ``` { "addresses_1": ["10.0.1.4","10.1.7.5"], "addresses_2": "10.0.1.4 10.1.7.5 ", "addresses_3": "["10.0.1.4","10.1.7.5"]" } ``` The `addresses_1` substitution works as you might want — `{{addresses}}` is an array, so it gets replaced with a proper JSON array containing the addresses. The second substitution also works. In that case, the template loops through each address in the array, and puts the values into a single string. The values don't get put in quotes, but they will have any quotes inside them escaped. The third substitution doesn't work properly — the addresses get turned into a JSON array of strings, but that gets surrounded by the quotes, resulting in invalid JSON. #### Utilizing the runZero HTML template When creating an alert template, the runZero HTML template option will wrap the provided alert template body with a runZero-provided HTML template. This option has been added to make it much easier to create consistent rich-content notification emails, and includes a base set of CSS classes you can apply to the contents of your template as you see fit. | Class name | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `padding-sm` | Applies a small amount of padding in each direction. | | `padding-md` | Applies a medium amount of padding in each direction. | | `color-yellow` | Applies a yellow text color to the target text | | `preamble` | Creates a "preamble" block intended to go below the header. `p` tags within this block have a slightly larger font size and line height. | | `card` | Creates a block that has a thin border, slightly rounded corners, and a slightly lighter background color than the main background color. | | `section` | Similar to the card block, but with a darker background and a small amount of bottom margin. `section` is intended to be used within `card`. | | `preserve-newlines` | Preserves newline characters in the contained text. `preserve-newlines` is intended to be paired with `section`, but can be used anywhere. | | `button` | Creates a button with styling similar to the standard button seen in the runZero console, with a light blue background, white text color, and slightly rounded corners. When paired with `size-lg`, the button is given a slightly larger font size and a minimum width. | Additionally, the following elements have specific styles assigned to them: | Tag name | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `h1` | Bold font-weight, white text color, a moderate amount of bottom margin, considerably larger font size, and center-aligned text. | | `h2` | Bold font-weight, white text color, a moderate amount of bottom margin, and a moderately larger font size. | | `h3` | Normal font-weight, white text color, a small amount of bottom margin. | | `p` | 8 pixel bottom margin | | `hr` | Thin light blue top border, with a considerable amount of margin above and below. | | `a` | Light blue text color. | Using this template type and these classes, here is an example of a template intended for use with the `site-created` event: ```html

Site created

A new site was created in an organization

{{site.name}} attributes

Created at: {{event.created_at}}

ID: {{site.id}}

Organization: {{organization.name}}

Created by {{event.source_type}}: {{event.source_name}}

View site
``` While we strive to maintain backwards compatibility for templates utilizing this template type, the available classes and predefined styling may be changed without warning. #### Inserting a value To insert a value, put the variable name in double ((curly brackets)), like this `{{variablename}}`. The following example shows how to insert the console address: ``` The runZero Console is at {{console}}. ``` #### Inserting a value from an object To insert a value from a specific object, separate the object name and field name with a dot, like this `{{object.fieldname}}`. The following example shows how to insert the organization name: ``` The organization name is {{organization.name}}. ``` #### Inserting multiple values from an object To insert multiple values from an object easily, use a section. You will need to start the section with `{{#objectname}}` and close it with a matching `{{/objectname}}` The following example shows how to insert the results from a scan that include total assets and number of assets changed: ``` Here are the results: {{#scan}} Scan found {{assets_total}} assets and changed {{assets_changed}} of them. {{/scan}} ``` #### What happens if a field contains multiple values? If a section refers to a field which contains multiple values, the template engine will loop through the values in the field, processing the section inside for each individual value. The following example loops through all of the assets in `report.new`, and for each one, outputs its `names` and `addresses` fields. If there is nothing stored in `report.new`, the section between the tags will not be rendered. ``` {{#report.new}} {{names}} {{addresses}} {{/report.new}} ``` Note that within a loop, you can still refer to values from the outer object. If a named value isn't found in the current loop object, the template engine will check the outer object. For example, this can be useful for referring to the `{{console}}` variable, which provides the root runZero console URL. #### Using boolean values You can use boolean values with the `{{#field}}{{/field}}` tags. If the value of the field is false, the section between the tags is not rendered. For example: ``` {{#query.truncated}} (Additional results were found but not included in this report) {{/query.truncated}} ``` ## Objects and fields reference To include runZero data and details in your alerts, you can build your template using the following objects and fields. ### globals | Field | Contents | Example | | --------- | ---------------------------------------- | --------------------------- | | `console` | The base URL of the runZero web console. | https://console.runzero.com | ### event The following fields are available in the `event` object: | Field | Contents | Example | | ------------- | -------------------------------------------- | ------------------------------------ | | `action` | The action which triggered the event | task-completed | | `created_at` | When the event was created | 2021-04-02 12:50:26 -0500 | | `id` | The UUID of the event | b4b871db-bdf1-4a42-b82d-18ae99972228 | | `source_name` | Name of the thing which caused the event | Weekly security scan | | `source_type` | Type of thing which caused the event | task | | `success` | Whether the event succeeded | true | | `target_name` | Name of the object targeted by the event | Head Office | | `target_type` | The type of the object targeted by the event | site | ### task For events triggered by a task, the following fields are available in the `task` object: | Field | Contents | Example | |---------------|--------------------------------------------|--------------------------------------| | `created_at` | When the task was created | 2021-04-02 12:50:26 -0500 | | `created_by` | The user who created the task | user@example.com | | `description` | The description of the task | Weekly scan of main network | | `error` | The text of any error message for the task | explorer unavailable after 4h | | `id` | The UUID of the task | b4b871db-bdf1-4a42-b82d-18ae99972228 | | `name` | The name of the task | Weekly Scan | | `start_time` | When the task started | 2021-04-02 12:50:26 -0500 | | `status` | The status of the task | processed | | `type` | The type of task | scan | | `updated_at` | When the task was last updated | 2021-04-02 12:50:26 -0500 | | `url` | A URL linking to the task details | | ### organization The following fields are available in the `organization` object: | Field | Contents | Example | | ------ | ---------------------------- | ------------------------------------ | | `id` | The UUID of the organization | 86f12ee1-f0f1-419a-8799-63fff555777a | | `name` | The name of the organization | IT Dept. | ### site The following fields are available in the `site` object: | Field | Contents | Example | | ------ | -------------------- | ------------------------------------ | | `id` | The UUID of the site | 49f9323a-fea1-4afc-b490-2414c3aaaeee | | `name` | The name of the site | Head Office | ### rule The following fields are available in the `rule` object: | Field | Contents | Example | | ------------ | -------------------------------- | ------------------------------------ | | `action` | The action the rule said to take | notify | | `created_at` | When the rule was created | 2021-03-08 12:43:59 -0600 | | `created_by` | The user who created the rule | user@example.com | | `event` | The event triggering the rule | scan-completed | | `id` | The UUID of the rule | b2269a2c-69a1-4652-bcdf-899938886c17 | | `name` | The name of the Rule | Alert on scan | | `updated_at` | When the rule was last updated | 2021-04-01 17:09:40 -0500 | ### channel The following fields are available in the `channel` object: | Field | Contents | Example | | ------ | ----------------------- | ------------------------------------ | | `id` | The UUID of the channel | 7c9f0d5a-0f8e-4b3b-8a2e-1d9b5f1c2c3d | | `name` | The name of the channel | Notify auditors | | `type` | The channel type | email | ### scan For events triggered by a scan task, the following additional fields are available in a `scan` object: | Field | Contents | Example | | ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------ | | `explorer_id` | The UUID of the runZero Explorer which carried out the scan | 0fd44a62-d827-41c0-b26c-4837222d8888 | | `assets_changed` | The number of assets changed as a result of the scan | 9 | | `assets_ignored` | The number of assets ignored by the scan | 2 | | `assets_new` | The number of new assets detected by the scan | 2 | | `assets_offline` | The number of assets which were previously online but now offline | 1 | | `assets_online` | The number of assets previously offline but now online again | 2 | | `assets_total` | The total number of assets for the site scanned (including offline) | 11 | | `assets_unchanged` | The number of assets unchanged by the scan | 1 | | `assets_updated` | The total number of assets up-to-date as a result of the scan (changed + unchanged) | 15 | | `duration` | Duration of the scan in seconds | 26 | | `end_time` | When the scan ended | 2021-04-02 12:50:26 -0500 | | `excludes` | Any IP addresses excluded from the scan | 10.0.1.123 | | `id` | The UUID of the scan task | 894a112c-3fb9-4301-8da7-8ce7fffb4443 | | `name` | The name of the scan task | Weekly security scan | | `rate` | The scan rate | 1000 | | `recv_bytes` | How many bytes were received during the scan | 45176 | | `recv_error` | How many receive errors were detected | 1 | | `recv_packets` | How many data packets were received during the scan | 555 | | `scheduled_time` | When the scan was scheduled to run | 2021-04-02 12:48:00 -0500 | | `sent_bytes` | How many bytes were sent during the scan | 44740 | | `sent_error` | How many send errors were detected | 0 | | `sent_packets` | How many data packets were sent during the scan | 577 | | `start_time` | When the scan actually started | 2021-04-02 12:49:55 -0500 | | `tags` | An array of tags associated with the scan task | | | `targets` | The CIDR address ranges scanned | 10.0.1.0/24 | | `type` | The type of operation | scan | ### explorer For events triggered by a scan task, the following additional fields are available in an `explorer` object (runZero 2.1.8+): | Field | Contents | Example | | ------------- | ------------------------------------------------------------------ | ------------------------------------ | | `id` | The UUID of the runZero Explorer which carried out the scan | 0fd44a62-d827-41c0-b26c-4837222d8888 | | `name` | The name of the Explorer which carried out the scan | MM34B-2 | | `internal_ip` | The internal IP address of the Explorer which carried out the scan | 10.0.1.200 | ### search For events triggered by a ((search query rule)), the following additional fields are available in a `search` object: | Field | Contents | Example | | ------------ | ---------------------------------------------------- | ------------------------------------------------- | | `url` | A link to perform the same search | https://console.runzero.com/inventory/?search=... | | `found` | The number of matches found | 3 | | `comparator` | The operation used to compare the number of matches | >= | | `value` | The value the number of matches was compared against | 1 | ### report For "((scan completed))" events, a `report` object contains the following results from the scan: | Field | Contents | | ----------- | ----------------------------------------------------------------------- | | `truncated` | Whether the set of objects was truncated due to large numbers of assets | | `changed` | An array of changed assets (see below) | | `new` | An array of new assets (see below) | | `offline` | An array of assets now offline (see below) | | `online` | An array of assets now online (see below) | The limit on the number of objects passed to the template is 25 for email notifications, 10 for Webhook notifications. #### asset (from a scan report) Each asset returned as part of a scan report has the following fields: | Field | Contents | | |-----------------------|--------------------------------------------------------|--------------------------------------| | `addresses` | The IP address(es) of the asset | 10.0.1.123 | | `alive` | Whether the asset responded to probes | true | | `created_at` | The timestamp when the asset record was created | 2021-04-02 12:50:26 -0500 | | `criticality_rank` | The criticality rank from (0-5) | 1 | | `detected_by` | The method by which the asset was detected | arp | | `domains` | Any domains the asset was found in | WORKGROUP | | `first_seen` | The timestamp when the asset was first seen | 2021-04-02 12:50:26 -0500 | | `hw` | A summary of the asset hardware | HP LaserJet Pro | | `id` | The UUID of the asset | b38295fb-bef1-fa42-b82d-18ae99972228 | | `last_seen` | The timestamp when the asset was most recently seen | 2021-04-02 12:50:26 -0500 | | `macs` | Any MAC addresses detected for the asset | 00:56:55:00:91:04 | | `modified_risk_rank` | The risk rank after applying user overrides | 2 | | `names` | Any names detected for the asset | LP538N | | `os` | A summary of the asset's operating system | Linux | | `outlier_score` | The normalized outlier score (0-5) | 2 | | `risk_rank` | The normalized risk rank (0-4) | 4 | | `service_count` | How many services the asset is running | 4 | | `software_count` | How many software entries were identified on the asset | 10 | | `type` | The type of asset | Router | | `updated_at` | The timestamp when the asset record was last updated | 2021-04-02 12:50:26 -0500 | | `vulnerability_count` | How many vulnerabilies were identified on the asset | 4 | ### query {#query-variables} For query events, the following data is provided in the `query` variable: | Field | Contents | | ----------- | -------------------------------------------------------------------------------------- | | `count` | The number of rows matching the search query | | `assets` | If it was an asset search, the array of assets matching the query | | `services` | If it was a service search, the array of services matching the query | | `wlans` | If it was a wireless network search, the array of wireless networks matching the query | | `truncated` | Whether the set of assets was truncated due to the query returning a large number | The limit on the number of assets passed to the template from a query is 25 for email notifications, 10 for Webhook notifications. #### asset (from a query) For assets returned from a query rule, the following fields are available: | Field | Contents | | | --------------- | ---------------------------------------------------- | -------------------------------------- | | `addresses` | The IP address(es) of the asset | 10.0.1.123 | | `alive` | Whether the asset responded to probes | true | | `comments` | Any comments set in the asset record | | | `created_at` | The timestamp when the asset record was created | 2021-04-02 12:50:26 -0500 | | `detected_by` | The method by which the asset was detected | arp | | `domains` | Any domains the asset was found in | WORKGROUP | | `first_seen` | The timestamp when the asset was first seen | 2021-04-02 12:50:26 -0500 | | `hw` | A summary of the asset hardware | ThinkPad X1 | | `id` | The UUID of the asset | b38295fb-bef1-fa42-b82d-18ae99972228 | | `last_seen` | The timestamp when the asset was most recently seen | 2021-04-02 12:50:26 -0500 | | `macs` | The list of MAC addresses associated with the asset | [F4:F5:E8:89:92:31, 00:D0:2D:9F:47:77] | | `names` | Any names detected for the asset | laptop.local | | `organization` | The organization the asset belongs to | IT | | `os` | A summary of the asset's operating system | Windows 10 | | `service_count` | How many services the asset is running | 4 | | `site` | The site the asset was detected at | New York | | `tags` | An array of tags set on the asset | | | `type` | The type of asset | Thermostat | | `updated_at` | The timestamp when the asset record was last updated | 2021-04-02 12:50:26 -0500 | #### service (from a query) For services returned from a query rule, the following fields are available, some of which are taken from the associated asset: | Field | Contents | Example | | --------------- | --------------------------------------------------------------------------- | -------------------------------------- | | `id` | The UUID of the service (not the asset) | b38efadb-61f1-f332-b92d-18ae99972228 | | `created_at` | When the service record was created | 2021-04-02 12:50:26 -0500 | | `summary` | A summary of the service | ciscoSystems | | `port` | The TCP/UDP port the service is on | 53 | | `vhost` | The vhost of the service | ftp.example.com | | `address` | The TCP/IP address of the service | 192.168.33.44 | | `transport` | The transport | udp | | `protocol` | The name of the protocol, if known | ssh | | `organization` | The name of the organization the service's asset belongs to | HR | | `site` | The name of the site the service's asset belongs to | Lab | | `alive` | Whether the asset offering the service was alive | true | | `last_seen` | When the asset was last seen | 2021-04-02 12:50:26 -0500 | | `first_seen` | When the asset was first seen | 2021-02-11 09:38:17 -0500 | | `type` | The asset type offering the service | Laptop | | `os` | The OS offering the service | Linux | | `hw` | The hardware offering the service | APC UPS | | `addresses` | A list of other IP addresses associated with the asset offering the service | [192.168.0.2, 192.168.0.3] | | `macs` | The list of MAC addresses associated with the asset | [F4:F5:E8:89:92:31, 00:D0:2D:9F:47:77] | | `names` | Any names associated with the asset | [fw-3, fw-3a] | | `tags` | Tags set on the asset | | | `domains` | Any domain associated with the asset | LOCAL | | `service_count` | A count of how many services the asset offers | 4 | | `comments` | Any comments set on the asset | | #### certificates (from a query) For certificates returned from a query rule, the following fields are available: | Field | Contents | Example | |-------------------------|--------------------------------------------------------------|-------------------------------------------| | `id` | The UUID of the certificate | ff6a8817-828a-43a3-b2cb-596dff5f0bd5 | | `type` | The type of certificate | x509 | | `self_signed` | Whether the certificate is self-signed | true | | `names` | All names associated with the certificate | ["example.com", "www.example.com"] | | `serial` | The serial number of the certificate | 0A014A1D4D0F861EC4C6EFD6E13A2F | | `validity_start` | When the certificate becomes valid | 2025-11-06 15:58:04 -0500 | | `validity_end` | When the certificate expires | 2025-11-08 15:58:04 -0500 | | `validity_period` | The total validity period in seconds | 172800 | | `public_key_algorithm` | The algorithm used for the public key | rsaEncryption | | `public_key_bits` | The size of the public key in bits | 2048 | | `signature_algorithm` | The algorithm used for the signature | sha256WithRSAEncryption | | `fp_bkhash` | The BKHash fingerprint of the certificate | d2c7e8f9a1b2c3d4e5f6 | | `fp_sha1` | The SHA1 fingerprint of the certificate | 3c482c71d874763e560c617129793dec76e91196 | | `fp_sha256` | The SHA256 fingerprint of the certificate | 19vJPgdyh3BdGgTiSSavQsKx133lzFkJhu51n6fzG+k= | | `cn` | The common name from the certificate subject | example.com | | `subject` | The subject distinguished name | CN=example.com,O=Example Corp,C=US | | `issuer` | The issuer distinguished name | CN=Example CA,O=Example Corp,C=US | | `is_ca` | Whether the certificate is a certificate authority | false | | `key_usage` | The key usage extension values | digitalSignature | | `ext_key_usage` | The extended key usage extension values | serverAuthentication | | `san_dns_names` | Subject Alternative Name DNS entries | ["example.com", "www.example.com"] | | `san_ip_addresses` | Subject Alternative Name IP entries | ["192.168.1.1"] | | `san_email_addresses` | Subject Alternative Name email entries | ["admin@example.com"] | | `san_uris` | Subject Alternative Name URI entries | ["spiffe://example.com/service"] | | `public_key_insecure` | Whether the public key is considered insecure | false | | `signature_insecure` | Whether the signature algorithm is considered insecure | false | | `public_key_parameters` | Parameters for the public key, if any | map[rsa_exponent:65537 rsa_modulus:244...]| | `name_constraints` | Name constraints extension, if present | map[] | | `comments` | Any comments set on the certificate | "Issued for legacy system" | | `tags` | Tags applied to the certificate | ["production", "web"] | | `risk_rank` | The calculated risk rank (-1..5) | 2 | | `modified_risk_rank` | The modified risk rank if set | 1 | | `risk` | Either modified risk rank if set or risk_rank if unset as a name | "info" | | `vulnerability_count` | Number of vulnerabilities associated | 3 | | `service_address` | The address of the associated service | 192.168.1.10 | | `service_port` | The port of the associated service | 443 | | `service_transport` | The transport protocol of the service | tcp | | `asset_site_id` | The UUID of the associated site | 49f9323a-fea1-4afc-b490-2414c3aaaeee | | `asset_site_name` | The name of the associated site | "Head Office" | | `asset_id` | The UUID(s) of associated assets | b38295fb-bef1-fa42-b82d-18ae99972228 | #### wlan (wireless LAN, from a query) For wireless lans (wlans) returned from a query rule, the following fields are available: | Field | Contents | Example | | ---------------- | ----------------------------------------------------------- | ------------------------------------ | | `id` | The UUID of the wireless LAN in runZero's database | f938934b-ae23-f112-b23d-18ae99972228 | | `last_seen` | When the wlan was last seen | 2021-04-02 12:50:26 -0500 | | `essid` | The ESSID of the network | Free WiFi | | `bssid` | The ESSID of the network | c4:41:1e:99:88:77 | | `type` | The type of wireless network | infrastructure | | `authentication` | The authentication used to access the network | WPA2-PSK | | `encryption` | The encryption used to protect data | AES | | `signal` | The signal strength as a percentage | 86 | | `channels` | The channel of the network | 11 | | `organization` | The name of the organization the service's asset belongs to | HR | | `site` | The name of the site the service's asset belongs to | Lab | ### findings_with_instances | Field | Contents | Example | |-------------------------------|-----------------------------------------------------------------|-------------------------------------------------| | `finding_category` | The category of the finding | Open Access | | `finding_code` | The code of the finding | rz-finding-open-access-default-credentials | | `finding_id` | The ID of the finding | b1f8a2e7-3c4d-4e6a-9c2f-1a5e7d8b9c0a | | `finding_name` | The name of the finding | Service Accessible With Default Credentials | | `finding_risk_rank` | The normalized risk rank of the finding (0-4) | 3 | | `finding_vulnerability_count` | How many vulnerabilities are associated with the finding; the same value as `new_vulnerability_count` | 8 | | `new_vulnerability_count` | How many vulnerabilities are associated with the finding after the task was run | 8 | | `old_vulnerability_count` | How many vulnerabilities were associated with the finding the last time the task was run | 5 | | `organization_id` | The ID of the organization | e2d3c4b5-6a7b-8c9d-0e1f-2a3b4c5d6e7f | | `site_id` | The ID of the site | f3e4d5c6-b7a8-9c0d-1e2f-3a4b5c6d7e8f | | `site_name` | The name of the site | Primary | | `task_id` | The ID of the task | a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d | | `task_name` | The name of the task | Metrics | | `task_start_time` | The start time of the task | 2026-03-02 11:16:59 -0500 | | `task_type` | The type of the task | analysis | ### rapid_response_published For rapid-response-published events, the `rapid_response_published` object contains `new`, `removed` and `updated` lists. The objects in these lists have the following fields available: | Field | Contents | Example | | ------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `id` | The UUID of the new rapid response query | f938934b-ae23-f112-b23d-18ae99972228 | | `name` | The name of the query | Rapid Response: Assets with multiple RCE exploits | | `description` | Plaintext description of the query | Certain assets can be exploited | | `solution` | Plaintext description of how to resolve the issue exposed by this query | Update the Chipland Exploitable NVR to v3.2 or newer | | `query` | The query contents | `hw:="Chipland Exploitable NVR"` | | `effective_query` | Query contents that are used to match assets. Includes any system predicates, such as `alive:t`. | `alive:t AND (hw:="Chipland Exploitable NVR")` | | `finding_code` | The finding code for the query, if assigned | rz-finding-rapid-response-assets | | `exploitable` | Whether or not the rapid response is known exploitable | true | | `cve` | Newline-separated list of CVEs that may apply to this query | `CVE-2025-12345\nCVE-2025-12346` | | `console_inventory_path` | The path to the console inventory page for the query | `/inventory` | | `attributes` | Various miscellaneous attributes, such as reference URLs and runZero blog links. | See example below table | Example attributes object: ```json { "links": { "rz_blog": [ { "title": "How to find Chipland Exploitable NVR on your network", "url": "https://www.runzero.com/blog/" } ], "urls": [ { "url": "https://example.local/1.html" }, { "url": "https://example.local/2.html" } ] } } ``` ### rapid_response_with_matches For rapid-response-with-matches events, the following fields are available: | Field | Contents | Example | | ----------- | -------------------------------------------------------------------------------------------------- | ------------------------------------- | | `id` | The UUID of the rapid response query | f938934b-ae23-f112-b23d-18ae99972228 | | `query` | Various attributes relating to the query. See `rapid_response_published` for the fields available. | See `rapid_response_published` fields | | `old_count` | How many resources matched last time this query was run. | 0 | | `new_count` | How many resources matched the most recent time this query was run. | 2 | ## Example: Alert when scan completes Let's take an example of something you might want to get alerted on: completed scans. We can create a rule that emails us when a scan completes, and provides us with some details, such as the number of new, online, offline, and modified assets. We'll build these details into our template. ### Step 1. Create a template. You can create a template from the [Alerts](https://console.runzero.com/alerts/template/create/) page. - Name the template something like `Email the team when a scan completes.` - For the template type, choose `HTML`, since we want to use this template for emails. - For the subject line, enter something that's descriptive, like `runZero scan {{scan.name}} completed at {{scan.end_time}}`. You can use the Mustache syntax for the subject. ### Step 2. Create the body message Now, let's create the email body. We want the email to tell us how many new, online, offline, and modified assets there are, as well as give us details on the new assets discovered. The body looks like this: ```

{{site.name}}

Scan Results

{{#scan}}
  • {{assets_new}} new assets
  • {{assets_online}} online assets
  • {{assets_offline}} offline assets
  • {{assets_changed}} modified assets
{{/scan}}

New assets

    {{#report.new}}
  • {{names}} {{addresses}} {{os}}
    • {{/report.new}} {{^report.new}}
  • No new assets were discovered.
    • {{/report.new}}

View the scan results

``` **See that ((caret)) (^)?** It represents inverted sections. These sections only render when the list is empty or the value is empty or false. ### Step 3. Save the template and create a rule The template is now available for you to choose when you [create a rule](https://console.runzero.com/alerts/rule/create/). ## Sample JSON templates ### A JSON array of new assets found by a scan ```json [ {{#report.new}} { "addresses": "{{addresses}}", "alive": "{{alive}}", "detected_by": "{{detected_by}}", "domains": "{{domains}}", "first_seen": "{{first_seen}}", "hw": "{{hw}}", "names": "{{names}}", "os": "{{os}}", "type": "{{type}}" }, {{/report.new}} null ] ``` The trailing `null` in the array is so that the array is valid JSON, because JSON doesn't allow trailing commas. ### All available attributes Output all available variables and their attributes as a JSON object: ```json {{.}} ``` Alternatively, you can build your own JSON array with all attributes: ```json { "event": { "action": "{{event.action}}", "created_at": "{{event.created_at}}", "id": "{{event.id}}", "source_name": "{{event.source_name}}", "source_type": "{{event.source_type}}", "success": "{{event.success}}", "target_name": "{{event.target_name}}", "target_type": "{{event.target_type}}" }, "organization": { "name": "{{organization.name}}", "id": "{{organization.id}}" }, "site": { "name": "{{site.name}}", "id": "{{site.id}}" }, "report": { "truncated": "{{report.truncated}}", "changed": "{{report.changed}}", "new": "{{report.new}}", "offline": "{{report.offline}}", "online": "{{report.online}}" }, "rule": { "action": "{{rule.action}}", "created_at": "{{rule.created_at}}", "created_by": "{{rule.created_by}}", "event": "{{rule.event}}", "id": "{{rule.id}}", "name": "{{rule.name}}", "updated_at": "{{rule.updated_at}}" }, "scan": { "explorer_id": "{{scan.explorer_id}}", "assets_changed": "{{scan.assets_changed}}", "assets_ignored": "{{scan.assets_ignored}}", "assets_new": "{{scan.assets_new}}", "assets_offline": "{{assets_offline}}", "assets_online": "{{scan.assets_online}}", "assets_total": "{{scan.assets_total}}", "assets_unchanged": "{{scan.assets_unchanged}}", "assets_updated": "{{scan.assets_updated}}", "duration": "{{scan.duration}}", "end_time": "{{scan.end_time}}", "excludes": "{{scan.excludes}}", "id": "{{scan.id}}", "name": "{{scan.name}}", "rate": "{{scan.rate}}", "recv_bytes": "{{scan.recv_bytes}}", "recv_error": "{{scan.recv_error}}", "recv_packets": "{{scan.recv_packets}}", "scheduled_time": "{{scan.scheduled_time}}", "sent_bytes": "{{scan.sent_bytes}}", "sent_error": "{{scan.sent_error}}", "sent_packets": "{{scan.sent_packets}}", "start_time": "{{scan.start_time}}", "tags": "{{scan.tags}}", "targets": "{{scan.targets}}", "type": "{{scan.type}}" }, "explorer": { "id": "{{explorer.id}}", "name": "{{explorer.name}}", "internal_ip": "{{explorer.internal_ip}}" }, "search": { "url": "{{search.url}}", "found": "{{search.found}}", "comparator": "{{search.comparator}}", "value": "{{search.value}}" }, "query": { "count": "{{query.count}}", "assets": "{{query.assets}}", "services": "{{query.services}}", "wlans": "{{query.wlans}}", "truncated": "{{query.truncated}}" } } ``` ### Event attributes only ```json { "event": {{event}} } ``` or ```json { "action": "{{event.action}}", "created_at": "{{event.created_at}}", "id": "{{event.id}}", "source_name": "{{sevent.ource_name}}", "source_type": "{{event.source_type}}", "success": "{{event.success}}", "target_name": "{{event.target_name}}", "target_type": "{{tevent.arget_type}}" } ``` ### Organization attributes only ```json { "organization": {{organization}} } ``` or ```json { "name": "{{organization.action}}", "id": "{{organization.id}}" } ``` ### Site attributes only ```json { "site": {{site}} } ``` or ```json { "name": "{{site.action}}", "id": "{{site.id}}" } ``` ### Report attributes only ```json { "report": {{report}} } ``` or ```json { "truncated": "{{report.truncated}}", "changed": "{{report.changed}}", "new": "{{report.new}}", "offline": "{{report.offline}}", "online": "{{report.online}}" } ``` ### Rule attributes only ```json { "rule": {{rule}} } ``` or ```json { "action": "{{rule.action}}", "created_at": "{{rule.created_at}}", "created_by": "{{rule.created_by}}", "event": "{{rule.event}}", "id": "{{rule.id}}", "name": "{{rule.name}}", "updated_at": "{{rule.updated_at}}" } ``` ### Scan attributes only ```json { "scan": {{scan}} } ``` or ```json { "explorer_id": "{{scan.explorer_id}}", "assets_changed": "{{scan.assets_changed}}", "assets_ignored": "{{scan.assets_ignored}}", "assets_new": "{{scan.assets_new}}", "assets_offline": "{{assets_offline}}", "assets_online": "{{scan.assets_online}}", "assets_total": "{{scan.assets_total}}", "assets_unchanged": "{{scan.assets_unchanged}}", "assets_updated": "{{scan.assets_updated}}", "duration": "{{scan.duration}}", "end_time": "{{scan.end_time}}", "excludes": "{{scan.excludes}}", "id": "{{scan.id}}", "name": "{{scan.name}}", "rate": "{{scan.rate}}", "recv_bytes": "{{scan.recv_bytes}}", "recv_error": "{{scan.recv_error}}", "recv_packets": "{{scan.recv_packets}}", "scheduled_time": "{{scan.scheduled_time}}", "sent_bytes": "{{scan.sent_bytes}}", "sent_error": "{{scan.sent_error}}", "sent_packets": "{{scan.sent_packets}}", "start_time": "{{scan.start_time}}", "tags": "{{scan.tags}}", "targets": "{{scan.targets}}", "type": "{{scan.type}}" } ``` ### Explorer attributes only ```json { "explorer": {{explorer}} } ``` or ```json { "id": "{{explorer.id}}", "name": "{{explorer.name}}", "internal_ip": "{{explorer.internal_ip}}" } ``` ### Search attributes only ```json { "search": {{search}} } ``` or ```json { "url": "{{search.url}}", "found": "{{search.found}}", "comparator": "{{search.comparator}}", "value": "{{search.value}}" } ``` ### Query attributes only ```json { "query": {{query}} } ``` or ```json { "count": "{{query.count}}", "assets": "{{query.assets}}", "services": "{{query.services}}", "wlans": "{{query.wlans}}", "truncated": "{{query.truncated}}" } ``` ### Asset, service, or wireless query alert to SIEM or SOAR ```json { "organization": { "name": "{{organization.name}}", "id": "{{organization.id}}" }, "site": { "name": "{{site.name}}", "id": "{{site.id}}" }, "rule": { "action": "{{rule.action}}", "created_at": "{{rule.created_at}}", "created_by": "{{rule.created_by}}", "event": "{{rule.event}}", "id": "{{rule.id}}", "name": "{{rule.name}}", "updated_at": "{{rule.updated_at}}" }, "search": { "url": "{{search.url}}", "found": "{{search.found}}", "comparator": "{{search.comparator}}", "value": "{{search.value}}" } } ``` ### Asset, service, or wireless query alert to Slack ```json { "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": ":red_circle: *runZero Alert* - {{rule.name}}" } }, { "type": "divider" }, { "type": "section", "text": { "type": "mrkdwn", "text": "*Rule information*\n\n_Name_: {{rule.name}}\n_Type_: {{rule.event}}\n_Link_: https://console.runzero.com/alerts/rule/{{rule.id}}" } }, { "type": "section", "text": { "type": "mrkdwn", "text": "*Match information*\n\n_Organization_: {{organization.name}}\n_Site_: {{site.name}}\n_Match count_: {{search.found}}\n_Search_: {{search.value}}\n_Link_: https://console.runzero.com/alerts/rule/{{search.url}}" } } ] } ``` ### Asset, service, or wireless query alert to Microsoft Teams ```json { "type": "message", "attachments": [ { "contentType": "application/vnd.microsoft.card.adaptive", "contentUrl": null, "content": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "TextBlock", "text": "runZero Alert - {{rule.name}}" }, { "type": "TextBlock", "text": "**Rule information**\n\n_Name_: {{rule.name}}\n\n_Type_: {{rule.event}}\n\n_Link_: [Rule](https://console.runzero.com/alerts/rule/{{rule.id}})", "wrap": true }, { "type": "TextBlock", "text": "**Match information**\n\n_Organization_: {{organization.name}}\n\n_Site_: {{site.name}}\n\n_Match count_: {{search.found}}\n\n_Search_: {{search.value}}\n\n_Link_: [Search](https://console.runzero.com/alerts/rule/{{search.url}})", "wrap": true, "spacing": "Medium" } ] } } ] } ``` ## Data type accepted by each channel When you create a rule, the channel you select must accept the data type used by the template. For example, if you want to send a ((Slack)) notification, the template must be in plain text or JSON. Here are the data types accepted by each channel: | Channel | Data type | | --------------------- | ---------------------- | | Email | Plain text, HTML, JSON | | Webhook | Plain text, JSON | | Internal notification | Plain text | ## Managing templates Go to [Alerts > Templates](https://console.runzero.com/alerts/template/). From this page, you can create, edit, and delete templates. Before deleting templates, make sure they are not in use by any rules. If you delete a template that is in use by a rule, the rule will revert to the default template. --- docs/querying-your-data.md --- title: "Querying your data" --- runZero provides many ways to query your data. Generally, ((queries)) can be broken into two concepts: - Filters or parameters used in the search bars on pages across the console, or - System and custom queries for which match metrics are calculated as tasks complete. Both allow you to leverage the extensive query language to quickly find the information you're looking for. ## Filtering and searching data The various inventory pages are likely the main place you'd look to use these queries, but many other pages include the same type of search bar that can be used to filter results. The following documentation pages will help you craft a query that meets your needs: - [Syntax for crafting compound queries](docs/search-query-syntax.md) - [Examples to guide query development](docs/search-query-examples.md) - [Keywords that can be used across the inventory pages](docs/search-query-inventory.md) - [Keywords that can be used across other components of the console](docs/search-query-components.md) ## System and custom queries The [Queries page](https://console.runzero.com/queries/) serves as an inventory of all your saved queries. Saved queries can either be system queries published by runZero or custom queries created by you or your team. ### Standard query attributes Queries have the following standard attributes: - **Name**: A name for the saved query. - **Description**: A description of the saved query. - **Search query**: The query or parameters to search for matches to. - **Search live assets only**: When toggled to _Yes_ (default), `alive:t` is added to the search query to only include assets marked alive. - **Type**: The inventory the query will search. - **Category**: The category the query falls under. - **Severity**: A severity level for the query. - **Automatically track query results on the dashboard**: When toggled to _Yes_, the query and count of matches will be included in a component on the dashboard. ### Vulnerability record attributes System and custom queries can also be used to create and associate vulnerability records with matching assets. This will be enabled by default on some system queries. To have a query create vulnerability records, switch the **Apply a vulnerability record to matching assets** toggle to _Yes_, then complete the following fields: - **Vulnerability ID**: Choose a unique ID to track this vulnerability within runZero. - **CVEs**: Include a list of CVEs relevant to this vulnerability record (optional). - **Solution**: Provide context for how this vulnerability could be remediated on assets (optional). - **Risk**: Select a risk level to associate with the vulnerability. This impacts the [asset risk](docs/asset-risk-and-criticality.md). - **Exploitable**: Specify whether an exploit is available for the vulnerability. - **CVSS v3 base score**: The CVSS v3 base score (0.00 to 10.00). - **CVSS v3 temporal score**: The CVSS v3 temporal score (0.00 to 10.00). - **CVSS v2 base score**: The CVSS v2 base score (0.00 to 10.00). - **CVSS v2 temporal score**: The CVSS v2 temporal score (0.00 to 10.00). - **CPE 2.3 identifier**: Specify a relevant Common Platform Enumeration identifier in URI format (v2.3) to associate with the reported vulnerability (optional). ## Creating and editing queries Custom queries can be created by users with the default role of administrator or higher from the [Queries page](https://console.runzero.com/queries/) by clicking the **New query** button. Once created, custom queries can be edited and copied. System queries cannot be edited directly, but can be copied if you wish to make changes. --- docs/search-query-syntax.md --- title: "Search query syntax" aliases: ["/docs/search-query-list/"] --- runZero supports deep searching across the Asset, Service, and Wireless Inventory, across organizations and sites, and through the Query Library. The runZero Export API uses the same inventory ((search syntax)) to ((filter)) results. ## Query syntax ### Boolean operators Search queries can be combined through `AND` and `OR` operators and be grouped using parenthesis. #### AND For example, a Asset Inventory query of `os:"Windows 10" AND protocols:http AND protocols:smb2` will show only those assets where Windows 10 was identified and both SMB and a web server were discovered. Search values that contain spaces must be placed in double quotes. #### OR By contrast, the example query of `os:"Windows 10" AND protocols:http OR protocols:smb2` will search for Windows 10 running a web server `or` any assets with the SMB service exposed. In addition to `AND` and `OR`, the `NOT` operator can be used to filter a query. For example, the query `os:"Windows 10" AND NOT protocols:http` will show Windows 10 systems without a web server. If the negation should happen as the first term the `AND` should be dropped. The query `NOT protocol:http AND os:"Windows 10"` is equivalent to the previous search, with the terms reversed. ### Wildcard and fuzzy searches Most keywords are a fuzzy match by default. To force an exact match, prefix match, or suffix match, the `=` prefix can be applied to the search term, with the `%` character used as a wildcard. To search an operating system name of just `Windows`, the Asset Inventory query would be `os:="Windows"`, while to specify a prefix match of `Ubuntu Linux`, the query `os:="Ubuntu Linux%"` can be used. ### Single-character wildcard The `%` wildcard matches any number of characters. To match exactly one character, use the `_` single-character wildcard. For example, `os:="Window%"` will match both `Windows` and `Windows 10`, while `os:="Window_"` will match `Windows` but not `Windows 10`. ### Time and date values Time and date (timestamp) fields can be searched using `<` (less than) and `>` (greater than) operators to compare against the current time. You can also use `-` to compare to a relative time in the past, for example `<-3years` would look for timestamps that occurred before three years ago. Supported units: - hours - minutes - seconds - months - years A special value of `now` can also be used. For example, an asset search of `first_seen:<1year` would search for assets first detected this year. Other examples: ```plaintext first_seen:<3days ``` ```plaintext first_seen:>2019-08-01 ``` ```plaintext first_seen:>8/1/2019 ``` ```plaintext last_seen:<1week ``` ```plaintext last_seen:<2months ``` ```plaintext last_seen:<1year ``` ```plaintext created_at:>2weeks ``` ```plaintext created_at:<30minutes ``` ```plaintext updated_at:>1year ``` ```plaintext updated_at:<12hours ``` ```plaintext os_eol:4weeks ``` ```plaintext os_eol:<-2years ``` ```plaintext os_eol_extended:>now ``` ```plaintext os_eol_extended:>90days ``` ### Empty values To search for an empty value, the `=` prefix can be used with no value after. For example, the query `os:=` will find assets with no identified operating system. Note that this only works for single-valued attributes such as `os` and `type`; it won't work for multi-value attributes such as `names` or `addresses`. ### Asset and service inventory searches Asset and Service attributes support two special search types in addition to the documented keywords: * Asset Inventory searches treat unknown keywords as filters against individual Asset **attributes**. * Service Inventory searches treat unknown keywords as filters against individual Service **data** values. In situations where an Asset keyword conflicts with a Service data key, or an Asset attribute conflicts with a Service keyword, the prefixes `_asset.` and `_service.` can be used to disambiguate. Searches are handled slightly differently. Service queries can filter against Asset attributes (`os:linux`) and Service attributes (`banner:Password`), but the Asset queries are limited to summary information about services (`protocol:ssh`). --- docs/search-query-examples.md --- title: "Query examples" --- There are endless ways to combine terms and operators into effective queries, and the ((examples|example queries)) below can be used as-is or adjusted to meet your needs. ## Network configurations and access * Multihomed assets with public and private IP addresses: ```plaintext alive:t AND has_public:t AND has_private:t ``` * Multihomed assets connected only to private networks ```plaintext multi_home:t AND has_public:f ``` * Default SSH configuration using passwords for authentication: ```plaintext alive:t AND protocol:"ssh" AND ssh.authMethods:"=password" ``` * Microsoft FTP servers: ```plaintext alive:t AND protocol:"ftp" AND banner:"=%Microsoft FTP%" ``` * Remote access services/protocols: ```plaintext protocol:rdp OR protocol:vnc OR protocol:teamviewer ``` * Assets with public IPs running remote access services: ```plaintext has_public:t OR has_public:t AND alive:t AND (protocol:rdp OR protocol:vnc OR protocol:teamviewer) ``` * Open ports associated with cleartext protocols: ```plaintext port:21 OR port:23 OR port:80 OR port:443 OR port:139 OR port:445 OR port:3306 OR port:1433 OR port:161 OR port:8080 OR port:3389 OR port:5900 ``` * Telnet on nondefault ports: ```plaintext protocol:telnet AND NOT port:23 ``` * Windows assets offering SMB services: ```plaintext os:windows AND protocol:smb1 OR protocol:smb2 ``` * Switch assets accepting Username and Password authentication: ```plaintext type:switch AND (_asset.protocol:http AND NOT _asset.protocol:tls) AND ( html.inputs:"password:" OR last.html.inputs:"password:" OR has:http.head.wwwAuthenticate OR has:last.http.head.wwwAuthenticate ) ``` * Assets more than 8 hops away: ```plaintext attribute:"ip.ttl.hops" AND ip.ttl.hops:>"8 ``` ## Asset lifecycle and hardware * Assets created as a result of arbitrary responses: ```plaintext has_mac:f AND has_name:f AND os:= AND hardware:= AND detected_by:icmp AND service_count:<2 ``` * End of Life assets: ```plaintext os_eol:now ``` * EOL Linux operating systems: ```plaintext os:linux AND os_eol:" AND NOT authentication:"wpa2-enterprise" ``` * Find unknown BSSIDs broadcasting known ESSID (exclude known BSSIDs in query for gap analysis) ```plaintext essid:="" AND NOT bssid:"" ``` --- docs/search-query-inventory.md --- title: "Inventory keywords" --- The data across your runZero inventories can be queried and filtered using the [search syntax](docs/search-query-syntax.md) in conjunction with the available inventory keywords. Keywords and example values are documented for the following inventories: - [Assets](docs/search-query-assets.md) - [Services](docs/search-query-services.md) - [Software](docs/search-query-software-groups.md) - [Vulnerabilities](docs/search-query-vulnerabilities.md) - [Certificates](docs/search-query-certificates.md) - [Wireless networks](docs/search-query-wireless.md) - [Users](docs/search-query-users.md) - [Groups](docs/search-query-groups.md) --- docs/search-query-assets.md --- title: "Asset inventory" --- When viewing assets, you can use the following keywords to ((search|search assets)) and filter. ## User-specified fields ### Comments {#assets-comments} Use the syntax `comment:` to search comments on an asset. ```plaintext comment:"contractor laptop" ``` ```plaintext comment:"imaging server" ``` ### Tags {#assets-tags} Use the syntax `tag:` to search tags added to an asset. The term can be the tag name, or the tag name followed by an equal sign and the tag value. Tag value matches must be exact. ```plaintext tag:"group" ``` ```plaintext tag:"group=production" ``` ### Organization name or ID {#assets-organization} Use the syntax `organization:` to filter by organization name or ID. ```plaintext organization:runZero ``` ```plaintext organization:"Temporary Project" ``` ```plaintext organization:f1c3ef6d-cb41-4d55-8887-6ed3cfb3d42d ``` ### Site name or ID {#assets-site} Use the syntax `site:` to filter by site name or ID. ```plaintext site:Primary ``` ```plaintext site:"Branch Office" ``` ```plaintext site:ad67d649-041b-439d-af59-f200053a8899 ``` ### Explorer name or ID {#assets-explorer} Use the syntax `explorer:` to filter by Explorer name or ID. ```plaintext explorer:DESKTOP-AB451F ``` ```plaintext explorer:8b927a8e-d405-40e9-aa47-d6afc9bff237 ``` ### Hosted zone Use the syntax `hosted_zone:` to filter by the hosted runZero Explorer that found the asset. Using this filter after a hosted scan can be a good way to locate externally facing assets. ### Owner Use the syntax `owner:` to filter by owner name. ```plaintext owner:user@runzero.com owner:"Security Team" ``` ### Ownership status Use the syntax `owner_count:` to filter by owner count. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext owner_count:>0 owner_count:0 ``` Use the syntax `has_owner:` to find assets with owners or assets that are missing owners. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_owner:t has_owner:f ``` Use the syntax `ownership_type:` to filter assets by ownership type name. This will return assets that have an owner assigned for the specified ownership type. ```plaintext ownership_type:"Asset Owner" ownership_type:"Security Owner" ``` ## Asset fields ### Asset ID {#assets-ID} The ID field is the unique identifier for a given asset, written as a UUID. Use the syntax `id:` to filter by ID field. ```plaintext id:cdb084f9-4811-445c-8ea1-3ea9cf88d536 ``` ### Operating system {#assets-OS} The operating system field is a string describing the detected operating system software. This field is searched using the syntax `os:`. The OS version, if available, can be searched using `os_version:`. ```plaintext os:"Windows" ``` ```plaintext os:"Ubuntu Linux" ``` ```plaintext os_version:8 ``` ### OS CPE {#assets-cpe} The operating system Common Platform Enumeration (CPE) field is a string describing the detected operating system software aligned to the CPE naming scheme. This field is searched using the syntax `os.cpe23:`. In cases where runZero was able to fingerprint the operating system but the NIST database does not contain an official matching entry, an unofficial CPE will be generated and include `r0_unofficial` in the `other` field of the CPE. ```plaintext os.cpe23:"ubuntu" ``` ```plaintext os.cpe23:="cpe:/o:canonical:ubuntu_linux:22.04.1" ``` ```plaintext os.cpe23:="cpe:/o:alma:linux:-::~~~~~r0_unofficial" ``` ### Type {#assets-type} The type field is a string describing the detected system type, such as Desktop, Laptop, Server, BMC, or Mobile. Use the syntax `type:` to search this field. ```plaintext type:Desktop ``` ```plaintext type:BMC ``` ```plaintext type:"Game Console" ``` ### Hardware {#assets-hardware} The hardware field is a string describing the detected physical hardware, such as `macMini` or `Nintendo Switch`. Use the syntax `hardware:` to search this field. ```plaintext hardware:Switch ``` ```plaintext hardware:macMini ``` ### Hostnames {#assets-hostnames} The hostnames associated with an asset are obtained from DNS and exposed services. Use the syntax `name:` to search these names. ```plaintext name:"www" ``` ```plaintext name:"TV" ``` To search an asset where any asset has a specific prefix or suffix, use the `:=` exact match operator, and use `%` as a wildcard: ```plaintext name:="FTP.%" ``` ```plaintext name:="%-09" ``` Use the syntax `name_count:`to search the hostname count. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext name_count:>1 ``` Use the syntax `name_overlap:` to find assets sharing the same name. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext name_overlap:t ``` ### Domains {#assets-domains} The domains associated with an asset are obtained from DNS and exposed services. Use the syntax `domain:` to search the domain names. ```plaintext domain:"amazon.com" ``` ```plaintext domain:"corp.lan" ``` ```plaintext domain:"WORKGROUP" ``` The domain count can be searched using the syntax `domain_count:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext domain_count:>1 ``` ### Addresses {#assets-addresses} Use the syntax `address:` to search the addresses (both primary and secondary) associated with an asset, `primary_address:` to search only the primary addresses associated with an asset, or `secondary_address:` to search only the secondary addresses associated with an asset. These keywords also allow for CIDR mask matching, as well as wildcard matches using '%'. A comma-separated list of addresses will be used as an efficient multiple-match. ```plaintext address:192.168.0.1 ``` ```plaintext address:10.0.0 ``` ```plaintext address:10.1.2.0/24 ``` ```plaintext address:%.0.1 ``` ```plaintext address:10.%.254 ``` ```plaintext address:10.0.0.1,10.0.0.2,10.0.0.3 ``` Use the syntax `address_count:` and `address_extra_count:` to search address primary and secondary counts. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext address_extra_count:0 ``` Use the syntax `address_overlap:` to find assets sharing primary IP addresses. This can be further filtered to single sites using the `site` keyword. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext address_overlap:t ``` Use the syntax `address_extra_overlap:` to find assets sharing secondary IP addresses. This can be further filtered to single sites using the `site` keyword. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext address_extra_overlap:t ``` ### Networks {#assets-networks} Use the syntax `net:` to search the addresses (both primary and secondary) associated with an asset by CIDR mask. ```plaintext net:192.168.0.0/24 ``` ### Default SNMP communities {#assets-snmp} Use the syntax `has:snmp.v2DefaultCommunities` to search for assets with a default SNMP community (public, private, and other defaults). ```plaintext has:snmp.v2DefaultCommunities snmp.v2DefaultCommunities:public ``` ### Public address {#assets-publicIP} Use the keyword `has_public` and syntax `has_public:` to locate any asset with a non-reserved IP address. This often corresponds to public-facing systems, though public IPs can also be used internally behind a firewall. Note that public IPv6 addresses are included by this filter; to search for only public IPv4 addresses, you can use `has_public_v4`. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_public:true ``` ### Private address {#assets-privateIP} Use the keyword `has_private` and syntax `has_private:` to locate any asset with a private IP address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_private:false ``` ### IPv6 address {#assets-IPv6} Use the keyword `has_ipv6` and the syntax `has_ipv6:` to locate any asset with an identified IPv6 address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_ipv6:false ``` ### Link-local IPv6 address {#assets-linkLocal} Use the keyword `has_link_local` and syntax `has_link_local:` to locate any asset with an identified IPv6 link local (`fe80::`) address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_link_local:true ``` ### MAC address {#assets-MAC} Use the syntax `mac:` to search MAC addresses associated with an asset. ```plaintext mac:00:5c:04 ``` ```plaintext mac:00:00:1c ``` Use the syntax `mac_count:` to search the MAC address count. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext mac_count:>2 ``` If you use exact search (`:=`) you can also search for full MAC addresses in Cisco format or dash-separated format: ```plaintext mac:=00-10-fa-c2-bf-d5 ``` ```plaintext mac:=0010.fac2.bfd5 ``` Use the syntax `mac_overlap:` to find assets sharing the same MAC address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext mac_overlap:t ``` ### MAC address vendors {#assets-MACvendor} The vendor associated with the MAC addresses of an asset can be searched using the syntax `mac_vendor:`. ```plaintext mac_vendor:Apple ``` ```plaintext mac_vendor:"Intel Corporate" ``` To search only the vendor associated with the newest MAC address, use the syntax `newest_mac_vendor:` ```plaintext newest_mac_vendor:Apple ``` The MAC address vendor count can be searched using the syntax `mac_vendor_count:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext mac_vendor_count:0 ``` ### MAC address age {#assets-MACage} Use the syntax `mac_age:` to search the allocation date of the newest MAC address associated with an asset. The term supports the standard runZero [time comparison syntax][time]. ```plaintext mac_age:>1year ``` ```plaintext mac_age:<6months ``` ```plaintext mac_age:2019-12-31 ``` ### Outlier score {#assets-outlier} Use the syntax `outlier_score:` to search the calculated outlier score of assets. The outlier score is in the range 0 to 5 inclusive. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext outlier_score:>2 ``` ```plaintext outlier_score:0 ``` ### Upstream switch IP address {#assets-switch-ip} Use the syntax `switch.ip:
` to search the IP address of the upstream switch assets are connected to. ```plaintext switch.ip:192.168.1.1 ``` ```plaintext switch.ip:fe80::81f2:1c9d:5ac9:5420 ``` ### Upstream switch name {#assets-switch-name} Use the syntax `switch.name:` to search the hostname of the upstream switch assets are connected to. ```plaintext switch.name:"SWITCH-1" ``` ```plaintext switch.name:office ``` ### Upstream switch port {#assets-switch-port} Use the syntax `switch.port:
-` to search the port on the upstream switch assets that are connected to. ```plaintext switch.port:192.168.1.1-25 ``` ```plaintext switch.port:10.1.2.3-0/1/2 ``` ### Upstream switch shared port {#assets-switch-shared} Use the syntax `attribute:switch.portShared` to find assets which connect to a switch port that reports multiple MAC addresses. ```plaintext attribute:switch.portShared ``` ### Attributes {#assets-attributes} Use the syntax `attribute:` to search the asset attribute fields, such as the port used to detect the TTL. ```plaintext attribute:"ip.ttl.port" ``` ```plaintext attribute:"cpe:/a:isc:bind:9.11.3" ``` ```plaintext attribute:"9.11.3" ``` To determine if an asset has any attribute defined, use the `has:` keyword. The `has` keyword can be inverted to find missing fields with `not has:`. ```plaintext has:"ip.ttl.port" ``` ```plaintext not has:"rdns.names" ``` In addition to the standard fields, the following special attributes are available: * `has:screenshot` returns assets where at least one screenshot was obtained. * `has:icons` returns assets where at least one icon was obtained (HTTP, UPnP, or similar). * `has:uplink` returns assets seen in the CAM table of a network switch. * `has:downlink` returns assets where the CAM table was queried at least one other asset was connected. * `has:unmapped` returns assets where the CAM table was queried at least one other asset was connected but not identified by IP. The attribute can be specified as a term directly. If the attribute name conflicts with an existing term, the prefix `_asset.` can be specified to disambiguate the query. ```plaintext ip.ttl.port:80 ``` ```plaintext rdns.names:"router" ``` ```plaintext _asset.ip.ttl.hops:"1" ``` Foreign attributes from third-party inbound integrations can be queried using the syntax `@..:`. The table below includes the correct prefix for each integration. | Integration | Prefix | |----------------------------|------------------------------| | Miradore | `@miradore.dev.` | | AWS EC2 | `@aws.ec2.` | | AWS ELB & ELBv2 | `@aws.elb.` | | AWS RDS | `@aws.rds.` | | CrowdStrike | `@crowdstrike.dev.` | | Azure Load Balancer | `@azure.vm.` | | Azure VM | `@azure.vm.` | | Azure Scale Set VM | `@azure.vmss.` | | Censys | `@censys.host.` | | VMWare | `@vmware.vm.` | | GCP Load Balancer | `@gcp.lb.` | | GCP E2-Micro VM | `@gcp.vm.` | | GCP CloudSQL | `@gcp.cloudsql.` | | SentinelOne | `@sentinelone.dev.` | | Tenable.io & Nessus | `@tenable.dev.` | | Rapid7 Nexpose & InsightVM | `@rapid7.dev.` | | Qualys VMDR | `@qualys.dev.` | | Shodan | `@shodan.dev.` | | Azure AD | `azuread` | | Active Directory (LDAP) | `@ldap.computer.` | | Microsoft 365 Defender | `@ms365defender.dev.` | | Microsoft Intune | `@intune.dev.` | | Google Workspace ChromeOS | `@googleworkspace.chromeos.` | | Google Workspace Endpoint | `@googleworkspace.endpoint.` | | Google Workspace Mobile | `@googleworkspace.mobile.` | ```plaintext @aws.ec2.region:="us-east-2" ``` ```plaintext @crowdstrike.dev.agentVersion:="6.49.16201.0" ``` ```plaintext @googleworkspace.chromeos.model:="HP Chromebook" ``` Foreign attributes support semver-style comparison operators (`>`, `>=`, `<`, `<=`, `=`). Include at least the major and minor version number to use this search option. Any additional non-numerical text included in the prefix or suffix will be ignored in version comparison. ```plaintext @jamf.custom.osVersion:>6.0 ``` ## Asset services ### Service ports {#assets-ports} The TCP and UDP services associated with an asset can be searched by port number using the syntax `port:`. ```plaintext port:80 ``` ```plaintext port:161 ``` ### Service TCP ports {#assets-tcpPorts} Use the syntax `tcp:` to search the TCP services associated with an asset by port number. ```plaintext tcp:443 ``` To search for assets with a specific list of TCP ports open, you can use the syntax `service_ports_tcp:=`. Values should be in ascending numerical order, and separated by commas. ```plaintext service_ports_tcp:=80,443 ``` ### Service UDP ports {#assets-udpPorts} Use the syntax `udp:` to search UDP services associated with an asset by port number. ```plaintext udp:53 ``` To search for assets with a specific list of UDP ports open, you can use the syntax `service_ports_udp:=`. Values should be in ascending numerical order, and separated by commas. ```plaintext service_ports_udp:=53,123 ``` ### Service protocols {#assets-protocols} Use the syntax `service_protocols:` (or `protocol:` for short) to search the identified service protocols associated with an asset. ```plaintext protocol:http ``` ```plaintext service_protocol:telnet ``` The protocol count can be searched using the syntax `protocol_count:`. This search supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext protocol_count:>1 ``` ### Service products {#assets-products} Use the syntax `service_products:` (or `product:` for short) to search for the identified service products associated with an asset. ```plaintext product:openssh ``` ```plaintext service_products:nginx ``` The product count can be searched using the syntax `product_count:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext product_count:>3 ``` ### Service counts {#assets-counts} Use the following keywords to search the number of services associated with an asset can be searched by port number: * `service_count_tcp:` * `service_count_udp:` * `service_count_icmp:` * `service_count_arp:` These keywords support numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). Examples include: ```plaintext service_count_tcp:>=5 ``` ```plaintext service_count_arp:0 ``` ```plaintext service_count_udp:<=1 ``` ## Asset tracking fields ### Timestamps {#assets-timestamps} Use the following syntaxes to search the asset timestamp fields (`first_seen`, `last_seen`, `created_at`, `updated_at`, `os_eol`, `os_eol_extended`): * `first_seen:` * `last_seen:` * `created_at:` * `updated_at:` * `os_eol:` * `os_eol_extended:` The term supports the standard runZero [time comparison syntax][time]. ```plaintext first_seen:<3days ``` ```plaintext first_seen:>2019-08-01 ``` ```plaintext first_seen:>8/1/2019 ``` ```plaintext last_seen:<1week ``` ```plaintext last_seen:<2months ``` ```plaintext last_seen:<1year ``` ```plaintext created_at:>2weeks ``` ```plaintext created_at:<30minutes ``` ```plaintext updated_at:>1year ``` ```plaintext updated_at:<12hours ``` ```plaintext os_eol:4weeks ``` ```plaintext os_eol_extended:>now ``` ```plaintext os_eol_extended:>90days ``` ### Online status {#assets-online} Use the syntax `online:` or the inverse syntax `offline:` to search the online status of an asset. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext online:t ``` ```plaintext online:1 ``` ```plaintext offline:0 ``` ### Operating system support status {#assets-os-eol} The syntax `os_eol_expired:` can be used to find identify assets based on whether their operating systems are End of Life (EOL). This field evaluates both the `os_eol` and `os_eol_extended` values to only return assets with expired coverage. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext os_eol_expired:t ``` ```plaintext os_eol_expired:1 ``` ```plaintext os_eol_expired:no ``` ### Detection method {#assets-detection} The detected by attribute of an asset can be searched using the syntax `det:` or `detected_by:`. The term is one of `arp`, `icmp`, `-tcp`, or `-udp`. In the case of multiple detections, the priority goes `arp`, `icmp`, and then the first detected service. ```plaintext det:arp ``` ```plaintext detected_by:80-tcp ``` ```plaintext det:53-udp ``` ### Time to Live (TTL) comparisons {#assets-TTL} Use the syntax `ttl:` and `lowest_ttl:` to search the lowest TTL of an asset. TTL is the estimated number of hops between the scan source and the asset. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext lowest_ttl:>3 ``` ### Round Trip Time (RTT) comparisons {#assets-RTT} Use the syntax `rtt:` and `lowest_rtt:` to search the lowest RTT for an asset. RTT is the round-trip response time of a given probe measured in nanoseconds (1,000,000 == 1ms). This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext lowest_rtt:>50000000 ``` ### Multiple MAC address status {#assets-multipleMAC} Use the syntax `multi_mac:` to determine if an asset has multiple MAC addresses. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext multi_mac:t ``` ### Any MAC address status {#assets-anyMAC} Use the syntax `has_mac:` to find assets with any MAC addresses. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_mac:yes ``` ```plaintext has_mac:f ``` ### Multiple IP address status {#assets-multipleIP} Use the syntax `multi_home:` to determine if an asset has multiple IP addresses. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext multi_home:t ``` ### Multiple hostname status {#assets-multipleHostname} Use the syntax `multi_name:` to find assets with multiple hostnames. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext multi_name:yes ``` ```plaintext multi_name:false ``` ### Software installations {#assets-software} Use the syntax `software:>` to find assets with associated software. The term has three forms: - `software:` will look for any assets with a software product that matches the term. - `software:/` will look for any assets with a software product and version that matches the term exactly. - `software://` will look for any assets with a software vendor, product, and version that matches the term exactly. All three forms allow the use of `%` as a wildcard (beginning, middle, or end of the term). Version terms can be specified with comparators to search for versions that are less than or greater than a specific version. For example `software:"Google/Google Chrome/>=135"` will returns all assets with Google Chrome version 135 or greater. ```plaintext software:IIS ``` ```plaintext software:Microsoft/IIS/10.0 ``` ## Certificate fields {#asset-certificates} Certificate-related fields can be searched using the following keywords. ### Certificate ID {#asset-certificate-id} Use the syntax `certificate_id:` to filter by certificate ID. ```plaintext certificate_id:4e3a2b1c-5d6f-7a8b-9c0d-1e2f3a4b5c6d ``` ### Certificate type {#asset-certificate-type} Use the syntax `certificate_type:` to search by certificate type. ```plaintext certificate_type:"x509" ``` ### Certificate serial {#asset-certificate-serial} Use the syntax `certificate_serial:` to search by certificate serial number. ```plaintext certificate_serial:"01A23B45C" ``` ### Certificate public key {#asset-certificate-public-key} Use the syntax `certificate_public_key:` to search by certificate public key. ```plaintext certificate_public_key:"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..." ``` ### Certificate public key algorithm {#asset-certificate-public-key-algorithm} Use the syntax `certificate_public_key_algorithm:` to search by certificate public key algorithm. ```plaintext certificate_public_key_algorithm:"ecPublicKey" ``` ### Certificate signature {#asset-certificate-signature} Use the syntax `certificate_signature:` to search by certificate signature. ```plaintext certificate_signature:"abcdef1234567890" ``` ### Certificate signature algorithm {#asset-certificate-signature-algorithm} Use the syntax `certificate_signature_algorithm:` to search by certificate signature algorithm. ```plaintext certificate_signature_algorithm:"rsaEncryption" ``` ### Certificate fingerprint (bkhash) {#asset-certificate-bkhash} Use the syntax `certificate_fp_bkhash:` to search by certificate fingerprint (bkhash). ```plaintext certificate_fp_bkhash:"d2c7e8f9..." ``` ### Certificate fingerprint (SHA1) {#asset-certificate-sha1} Use the syntax `certificate_fp_sha1:` to search by certificate SHA1 fingerprint. ```plaintext certificate_fp_sha1:"349eb7db55bbad9d7deabc5effdfd5521ed984a0" ``` ### Certificate fingerprint (SHA256) {#asset-certificate-sha256} Use the syntax `certificate_fp_sha256:` to search by certificate SHA256 fingerprint. ```plaintext certificate_fp_sha256:"SHA256:Sc0pLUCvlNaGtu4Xy2fOTe1A6cC+KyU3x7xuN8+aLtA=" ``` ### Certificate subject {#asset-certificate-subject} Use the syntax `certificate_subject:` to search by certificate subject. ```plaintext certificate_subject:"CN=example.com,O=ExampleCorp,C=US" ``` ### Certificate common name (CN) {#asset-certificate-cn} Use the syntax `certificate_cn:` to search by certificate common name. ```plaintext certificate_cn:"example.com" ``` ### Certificate issuer {#asset-certificate-issuer} Use the syntax `certificate_issuer:` to search by certificate issuing authority. ```plaintext certificate_issuer:"CN=Example CA,O=Example Corp,C=US" ``` ### Certificate subject key ID {#asset-certificate-subject-key-id} Use the syntax `certificate_subject_key_id:` to search by certificate subject key ID. ```plaintext certificate_subject_key_id:"1234567890abcdef" ``` ### Certificate authority key ID {#asset-certificate-authority-key-id} Use the syntax `certificate_authority_key_id:` to search by certificate issuing authority key ID. ```plaintext certificate_authority_key_id:"abcdef1234567890" ``` --- docs/search-query-services.md --- title: "Service inventory" --- When viewing services, you can use the keywords in this section to ((search|search services)) and filter. ## Ports {#services-ports} The TCP and UDP services associated with a service can be searched by port number using the syntax `port:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext port:<=25 ``` ## TCP ports {#services-TCP} Use the syntax `tcp:` to search TCP service associated with a service by port number. ```plaintext tcp:53 ``` To search for all services on assets with a specific list of TCP ports open, you can use the syntax `service_ports_tcp:=`. Values should be in ascending numerical order, and separated by commas. ```plaintext service_ports_tcp:=80,443 ``` ## UDP ports {#services-UDP} Use the `udp:` syntax to search UDP services associated with a service by port number. ```plaintext udp:443 ``` To search for all services on assets with a specific list of UDP ports open, you can use the syntax `service_ports_udp:=`. Values should be in ascending numerical order, and separated by commas. ```plaintext service_ports_udp:=53,123 ``` ## Transport {#services-transport} Use the syntax `transport:` to search the transport associated with a service by name. ```plaintext transport:tcp ``` ```plaintext transport:udp ``` ```plaintext transport:icmp ``` ## Protocol {#services-protocol} Use the syntax `service_protocols:` (or `protocol:` for short) to search the protocols associated with services. ```plaintext protocol:http ``` ```plaintext protocol:telnet ``` ## Assets with product {#services-product} Use the syntax `service_products:` (or `product:` for short) to search for the identified service products associated with an asset, and return all services for the matching assets. ```plaintext product:openssh ``` ```plaintext service_products:nginx ``` ## Virtual Host (vHost) {#services-vhost} Use the syntax `vhost:` to search for virtual hosts associated with a service by name . ```plaintext vhost:"www" ``` ## Address {#services-address} Use the keyword `service_address` to match against the service IP address. ```plaintext service_address:192.168.0.1 ``` ## Public address {#services-public} Use the keyword `service_has_public` and syntax `service_has_public:` to locate any service with a non-reserved I address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext service_has_public:true ``` ## Private address {#services-private} Use the keyword `service_has_private` and syntax `service_has_private:` to locate any service with a private IP address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext service_has_private:false ``` ## IPv6 address {#services-IPv6} Use the keyword `service_has_ipv6` and the syntax `service_has_ipv6:` to locate any service with an identified IPv6 address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext service_has_ipv6:false ``` ## Link-local IPv6 address {#services-linkLocal} Use the keyword `service_has_link_local` and syntax `service_has_link_local:`to locate any service with an identified IPv6 link local (`fe80::`) address. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext service_has_link_local:true ``` ## Assets with outlier score {#services-outlier} You can use the syntax `outlier_score:` to search the calculated outlier score of assets, and return all services on those assets. The outlier score is in the range 0 to 5 inclusive. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext outlier_score:>2 ``` ```plaintext outlier_score:0 ``` ## Assets with MAC address vendors {#services-MACvendor} To search the vendors associated with the MAC addresses of an asset, and return all services on those assets, use the syntax `mac_vendor:`. ```plaintext mac_vendor:Apple ``` ```plaintext mac_vendor:"Intel Corporate" ``` To search only the vendor associated with the newest MAC address, use the syntax `newest_mac_vendor:` ```plaintext newest_mac_vendor:Apple ``` ## Assets with MAC address age {#services-MACage} To search the ages of the newest MAC addresses associated with each asset, and return all services associated with those assets, use the syntax `mac_age:`. The term supports the standard runZero [time comparison syntax][time]. ```plaintext mac_age:>1year ``` ```plaintext mac_age:<6months ``` ```plaintext mac_age:2019-12-31 ``` ## Attributes {#services-attributes} You can search all service attributes with the syntax `:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). If the attribute name conflicts with an existing term, the prefix `_service.` can be added to disambiguate the query. Note that service attributes can be slow and it is often better to prefix `_asset.protocol:` filter in front of the service attribute query. For example, to search for SSH banners, use the syntax `_asset.protocol:ssh AND banner:.` ```plaintext banner:password ``` ```plaintext service.product:"OpenSSH" ``` ```plaintext html.title:"Apache2 Ubuntu Default Page" ``` ```plaintext http.code:>=500 ``` ```plaintext screenshot.image.size:=>100000 ``` ```plaintext _service.arp.macVendor:Xerox ``` To determine if a service has an attribute at all, use the `has` keyword. The `has` keyword can be inverted to find missing fields, with `not has:`. ```plaintext has:"http.head.server" ``` ```plaintext not has:"html.title" ``` ## Certificate fields {#services-certificates} Certificates related to the service can be searched as well. ### Certificate ID {#service-certificate-id} Use the syntax `certificate_id:` to filter by certificate ID. ```plaintext certificate_id:4e3a2b1c-5d6f-7a8b-9c0d-1e2f3a4b5c6d ``` ### Certificate fingerprint (bkhash) {#service-certificate-fp-bkhash} Use the syntax `fp_bkhash:=` to search for services with certificates that match the specified bkhash fingerprint anywhere in the certificate chain. ```plaintext fp_bkhash:=d2c7e8f9a1b2c3d4e5f6 ``` ### Certificate fingerprint (SHA256) {#service-certificate-fp-sha256} Use the syntax `fp_sha256:=` to search for services with certificates that match the specified SHA256 fingerprint anywhere in the certificate chain. ```plaintext fp_sha256:=SHA256:19vJPgdyh3BdGgTiSSavQsKx133lzFkJhu51n6fzG+k= ``` ### Certificate fingerprint (SHA1) {#service-certificate-fp-sha1} Use the syntax `fp_sha1:=` to search for services with certificates that match the specified SHA1 fingerprint anywhere in the certificate chain. ```plaintext fp_sha1:=a1b2c3d4e5f6g7h8i9j0 ``` ### Certificate validity fields {#services-certificate-validity} Use the following syntax to search details about when the certificate found on the service was created. These fields support the standard runZero [time comparison syntax][time]. ```plaintext certificate_valid_from:>2025-01-01 certificate_valid_until:<2026-01-01 certificate_created_at:<1year certificate_updated_at:>2024-12-01 certificate_last_seen:<2months ``` ### Certificate authority key ID {#services-certificate-authority-key-id} Use the syntax `certificate_authority_key_id:` to search by certificate authority key ID. ```plaintext certificate_authority_key_id:"c03152cd5a50c3827c7471cecbe99cf97aeb82e2" ``` ### Certificate common name (CN) {#services-certificate-cn} Use the syntax `certificate_cn:` to search by certificate common name. ```plaintext certificate_cn:"example.com" ``` ### Certificate public key algorithm {#services-certificate-pk-algorithm} Use the syntax `certificate_public_key_algorithm:` to search by public key algorithm. ```plaintext certificate_public_key_algorithm:rsaEncryption ``` ### Certificate serial number {#services-certificate-serial} Use the syntax `certificate_serial:` to search by certificate serial number. ```plaintext certificate_serial:123456 ``` ### Certificate signature algorithm {#services-certificate-sig-algorithm} Use the syntax `certificate_signature_algorithm:` to search by signature algorithm. ```plaintext certificate_signature_algorithm:sha256WithRSAEncryption ``` ### Certificate subject key ID {#services-certificate-subject-key-id} Use the syntax `certificate_subject_key_id:` to search by subject key ID. ```plaintext certificate_subject_key_id:"c769916e10f850397928f62bd34ca6ec39d8e00a" ``` ### Certificate type {#services-certificate-type} Use the syntax `certificate_type:` to search by certificate type. ```plaintext certificate_type:x509 ``` ### Certificate key usage {#services-certificate-key-usage} Use the syntax `certificate_key_usage:` to search by key usage. ```plaintext certificate_key_usage:"digitalSignature" ``` ### Certificate extended key usage {#services-certificate-ext-key-usage} Use the syntax `certificate_ext_key_usage:` to search by extended key usage. ```plaintext certificate_ext_key_usage:"serverAuth" ``` ### Certificate OCSP server {#services-certificate-ocsp-server} Use the syntax `certificate_ocsp_server:` to search by OCSP server. ```plaintext certificate_ocsp_server:http://ocsp.example.com ``` ### Certificate CRL distribution points {#services-certificate-crl-distribution-points} Use the syntax `certificate_crl_distribution_points:` to search by CRL distribution point. ```plaintext certificate_crl_distribution_points:http://crl.example.com/ ``` ### Certificate issuing certificate URL {#services-certificate-issuing-certificate-url} Use the syntax `certificate_issuing_certificate_url:` to search by issuing certificate URL. ```plaintext certificate_issuing_certificate_url:http://issuer.example.com/ ``` ### Certificate signature {#services-certificate-signature} Use the syntax `certificate_signature:` to search by certificate signature. ```plaintext certificate_signature:Bden73ipj8B2xb1Ozy5nOvIytCktGrht5xL7ZfFlaLIBQxbGO5Iuf6Y1yICcEpYqsgSJS6JKCdw5dujmPmGRwBZfVhIbSRb0exFQ4BVp82WtDHfy3QBgcmtusRIxLyM5ToTT2O53NxaSGaw3IRLXZ0y343RGlKOyQxEXeoHbLsVrpmMrqAKkHJkhjTKn7E9WDc4RCsAvd13BIDP80dDWK7OMZJnCDXGQwz2MkAYZNyjRRXA5XeO2cvMq36/4phyJDhIz1oDgDLOFDnCGKkW5gc8MjE0uxFIYTHKNkx+2WIU/j4uQGNAJQbqqCnupV4qjI29PQFnFecnphkKw== ``` ### Certificate public key {#services-certificate-public-key} Use the syntax `certificate_public_key:` to search by certificate public key. ```plaintext certificate_public_key:MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ899KGnqHjVuBekYqosp2l8zWbiyu2I62CzaqaouLtqn1nXaQLMdruhlNN9ShCPfCM2JAROVjrd1PwhxLvJxAMbC+UJz2914SRn+lhFQl7yo03t+OoobwSXyj+ukbOHp1lYklYjMauScZScIDdPmLEjwDa8pfSr2TQoihjSDeawIDAQAB ``` ### Certificate comments {#services-certificate-comments} Use the syntax `certificate_comments:` to search comments on a certificate. ```plaintext certificate_comments:"our self signed wildcard" ``` ### Certificate self-signed {#services-certificate-self-signed} Use the syntax `certificate_self_signed:` to search for self-signed certificates. ```plaintext certificate_self_signed:true ``` ### Certificate hidden {#services-certificate-hidden} Use the syntax `certificate_hidden:` to search for certificates that have been hidden from the inventory. ```plaintext certificate_hidden:true ``` ### Certificate signature algorithm insecure {#services-certificate-signature-algorithm-insecure} Use the syntax `certificate_signature_algorithm_insecure:` to search for certificates with insecure signature algorithms. ```plaintext certificate_signature_algorithm_insecure:true ``` ### Certificate public key insecure {#services-certificate-public-key-insecure} Use the syntax `certificate_public_key_insecure:` to search for certificates with insecure public key algorithm and key size combinations. ```plaintext certificate_public_key_insecure:true ``` ### Certificate is CA {#services-certificate-is-ca} Use the syntax `certificate_is_ca:` to search for certificates that are certificate authorities (CAs). ```plaintext certificate_is_ca:true ``` --- docs/search-query-software-groups.md --- title: "Software inventory" --- When viewing ((software groups)), you can use the keywords in this section to search and filter. ## Vendor {#sgvendor} The vendor associated with a software can be searched by name using the syntax `vendor:`. ```plaintext vendor:oracle ``` ## Product {#sgproduct} The product associated with a software can be searched by name using the syntax `product:`. ```plaintext product:java ``` ## Version {#sgversion} The version associated with a software can be searched by name using the syntax `version:`. ```plaintext version:1.2.3 ``` --- docs/search-query-software.md --- title: "Software instance inventory" --- When viewing software instances on assets, you can use the keywords in this section to ((search|search software)) and filter. ## Source The source reporting the software installed can be searched or filtered by name using the syntax `source:`. ```plaintext source:runzero ``` ## Vendor The vendor associated with a software can be searched by name using the syntax `vendor:`. ```plaintext vendor:oracle ``` ## Product The product associated with a software can be searched by name using the syntax `product:`. ```plaintext product:java ``` --- docs/search-query-vulnerability-groups.md --- title: "Vulnerabilities inventory" --- When viewing ((vulnerability groups)), you can use the keywords in this section to search and filter. ## Name {#vulnerabilities-name} The name field can be searched using the syntax `name:`. ```plaintext name:"Cisco IOS Software DHCP Remote Code Execution Vulnerability" ``` ```plaintext name:"PHP < 5.3.12 / 5.4.2 CGI Query String Code Execution" ``` ## CVE {#vulnerabilities-CVE} The CVE field can be searched using the syntax `cve:`. ```plaintext cve:CVE-2021-44228 ``` ```plaintext cve:CVE-2016-2183 ``` ## KEV {#vulnerabilities-KEV} Membership in a Known Exploited Vulnerability (KEV) list can be searched using the syntax `kev:`. ```plaintext kev:t ``` will search for vulnerabilities that appear on a KEV list. Specific KEV lists can be searched by name. - `kev:cisa` will search for vulnerabilities listed as actively exploited in the [CISA Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog). - `kev:vulncheck` will search for vulnerabilities listed as actively exploited in the [VulnCheck Catalog](https://vulncheck.com/kev). - `kev:true` will search for vulnerabilities in either of the above lists. ## Severity {#vulnerabilities-severity} The severity field can be searched using the syntax `severity:`. ```plaintext severity:info ``` ```plaintext severity:medium ``` ## Risk {#vulnerabilities-risk} The `Risk` and `Risk Score` fields can be searched using either numeric or keyword values. Risk score is an integer from zero through four, where `0` is Info level risk and `4` indicates Critical risk. ```plaintext risk:"Critical" ``` ```plaintext risk:2 ``` ## Vulnerability instance count {#vulnerabilities-count} The `Asset count` field can be searched using the syntax `count:`. ```plaintext count:>0 ``` ## Site name or ID {#vulnerabilities-siteID} Use the syntax `site:` to filter by site name or ID. ```plaintext site:Primary ``` ## EPSS score {#vulnerabilities-EPSS} The EPSS score can be searched using the syntax `epss_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext epss_score:>0.5 ``` ```plaintext epss_score:<=0.1 ``` ```plaintext epss_score:=0.9 ``` ## Timestamps {#vulnerabilities-timestamps} Use the following syntaxes to search the vulnerability group timestamp fields (`created_at`, `suppressed_at`): * `created_at:` * `suppressed_at:` The term supports the standard runZero [time comparison syntax][time]. ```plaintext created_at:>2weeks ``` ```plaintext created_at:<30minutes ``` ```plaintext suppressed_at:<1day ``` ## Suppression {#suppressed-vuln-group} The current suppressed or unsuppressed state of vulnerability groups can be searched using the syntax `suppressed:`. ```plaintext suppressed:t ``` will search for vulnerability groups that are suppressed. Inversely, ```plaintext suppressed:f ``` will search for vulnerability groups that are not suppressed. A special value of `any` can be used to display all records, regardless of suppression settings: ```plaintext suppressed:any ``` will display both suppressed and unsuppressed vulnerability groups. Additionally, the user who performed the suppression can be found using the following syntaxes: ```plaintext suppressed_by: ``` --- docs/search-query-vulnerabilities.md --- title: "Vulnerability instance inventory" --- When viewing ((vulnerability instances)) on assets, you can use the following keywords to ((search|search vulnerabilities)) and filter information. ## Vulnerability ID {#vulnerability-ID} The ID field is the unique identifier for a given vulnerability, written as a UUID. Use the syntax `id:` to filter by the ID field. ```plaintext id:a124a141-e518-4735-9878-8e89c575b1d2 ``` ## Source {#vulnerability-source} The source reporting the vulnerability detected can be searched or filtered by name using the syntax `source:`. ```plaintext source:tenable ``` ## Severity {#vulnerability-severity} The severity field can be searched using the syntax `severity:`. ```plaintext severity:info ``` ```plaintext severity:medium ``` ## Severity score {#vulnerability-severityScore} The severity score can be searched using the syntax `severity_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext severity_score:<5.0 ``` ```plaintext severity_score:>=9.0 ``` ## Risk {#vulnerability-risk} The risk field can be searched using the syntax `risk:`. ```plaintext risk:none ``` ```plaintext risk:critical ``` ## Risk score {#vulnerability-riskScore} The risk score can be searched using the syntax `risk_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext risk_score:>7.0 ``` ```plaintext risk_score:=10.0 ``` ## Modified risk {#vulnerability-modifiedRisk} Vulnerabilities whose risk has been modified, either manually or by way of alert rule trigger `has_modified_risk:`. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext has_modified_risk:true ``` ```plaintext has_modified_risk:1 ``` ```plaintext has_modified_risk:no ``` ## Category {#vulnerability-category} The category field can be searched using the syntax `category:`. ```plaintext category:Local ``` ```plaintext category:Remote ``` ## Name {#vulnerability-name} The name field can be searched using the syntax `name:`. ```plaintext name:"Cisco IOS Software DHCP Remote Code Execution Vulnerability" ``` ```plaintext name:"PHP < 5.3.12 / 5.4.2 CGI Query String Code Execution" ``` ## Description {#vulnerability-description} The description field can be searched using the syntax `description:`. ```plaintext description:"The remote device is missing a vendor-supplied security patch." ``` ```plaintext description:"remote code execution" ``` ## Solution {#vulnerability-solution} The solution field can be searched using the syntax `solution:`. ```plaintext solution:patch ``` ```plaintext solution:upgrade ``` ## CVE {#vulnerability-CVE} The CVE field can be searched using the syntax `cve:`. ```plaintext cve:CVE-2021-44228 ``` ```plaintext cve:CVE-2016-2183 ``` ## KEV {#vulnerability-KEV} Membership in a Known Exploited Vulnerability (KEV) list can be searched using the syntax `kev:`. ```plaintext kev:t ``` will search for vulnerabilities that appear on a KEV list. Specific KEV lists can be searched by name. - `kev:cisa` will search for vulnerabilities listed as actively exploited in the [CISA Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog). - `kev:vulncheck` will search for vulnerabilities listed as actively exploited in the [VulnCheck Catalog](https://vulncheck.com/kev). - `kev:true` will search for vulnerabilities in either of the above lists. ## Exploitable {#vulnerability-exploitable} Vulnerabilities that are exploitable can be searched using the syntax `exploitable:`. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext exploitable:true ``` ```plaintext exploitable:1 ``` ```plaintext exploitable:no ``` ## CVSSv2 score {#vulnerability-CVSSv2} The CVSSv2 fields, `cvss2_base_score` and `cvss2_temporal_score`, can be searched using the syntax `cvss2_base_score:` and `cvss2_temporal_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext cvss2_base_score:>6.5 ``` ```plaintext cvss2_base_score:<=3.0 ``` ```plaintext cvss2_temporal_score:=10.0 ``` ```plaintext cvss2_temporal_score:<5.0 ``` ## CVSSv3 score {#vulnerability-CVSSv3} The CVSSv3 fields, `cvss3_base_score` and `cvss3_temporal_score`, can be searched using the syntax `cvss3_base_score:` and `cvss3_temporal_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext cvss3_base_score:>6.5 ``` ```plaintext cvss3_base_score:<=3.0 ``` ```plaintext cvss3_temporal_score:=10.0 ``` ```plaintext cvss3_temporal_score:<5.0 ``` ## EPSS score {#vulnerability-EPSS} The EPSS score can be searched using the syntax `epss_score:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext epss_score:>0.5 ``` ```plaintext epss_score:<=0.1 ``` ```plaintext epss_score:=0.9 ``` ## Address {#vulnerability-address} The address field can be searched using the syntax `address:`. ```plaintext address:192.168.0.1 ``` ## Transport {#vulnerability-transport} The transport field can be searched using the syntax `transport:`. ```plaintext transport:tcp ``` ```plaintext transport:udp ``` ## Port {#vulnerability-port} The port can be searched using the syntax `port:`. The term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). ```plaintext port:22 ``` ```plaintext port:443 ``` ## Operating system support status {#vulnerability-os-eol} The syntax `os_eol_expired:` can be used to find identify vulnerabilities on assets based on whether their operating systems are End of Life (EOL). This field evaluates both the `os_eol` and `os_eol_extended` values to only return vulnerabilities on assets with expired coverage. The term is a boolean value: - `true`, `t`, `1`, and `yes` represent _true_ - `false`, `f`, `0`, and `no` represent _false_ ```plaintext os_eol_expired:t ``` ```plaintext os_eol_expired:1 ``` ```plaintext os_eol_expired:no ``` ## Finding code {#vulnerability-finding-code} The finding code field is the unique identifier for a given finding. Use the syntax `finding_code:` to filter by the code field. ```plaintext finding_code:rz-finding-internet-exposed-database ``` ## Finding name {#vulnerability-finding-name} Use the syntax `finding_name:` to search by finding name. ```plaintext finding_name:"Internet Exposed Database" ``` ## Finding risk {#vulnerability-finding-risk} The `Finding Risk` and `Finding Risk Score` fields can be searched using either numeric or keyword values. Risk score is an integer from zero through four, where `0` is Info level risk and `4` indicates Critical risk. ```plaintext finding_risk:"Critical" ``` ```plaintext finding_risk:2 ``` ## Detection timestamps (first detected at, last detected at) {#vulnerability-detection} The timestamp fields, `first_detected_at` and `last_detected_at`, can be searched using the syntax `first_detected_at:` and `last_detected_at:`. The term supports the standard runZero [time comparison syntax][time]. ```plaintext first_detected_at:>2weeks ``` ```plaintext first_detected_at:<30minutes ``` ```plaintext last_detected_at:>1month ``` ```plaintext last_detected_at:2hours ``` ## Publication timestamps (published at) {#vulnerability-publication} The timestamp field, `published_at`, can be searched using the syntax `published_at:`. The term supports the standard runZero [time comparison syntax][time]. ```plaintext published_at:>2weeks ``` ```plaintext published_at:<30minutes ``` ## Timestamps (created at, updated at) {#vulnerability-timestamps} Use the following syntaxes to search the vulnerability timestamp fields (`created_at`, `updated_at`, `suppressed_at`): * `created_at:` * `updated_at:` * `suppressed_at:` The term supports the standard runZero [time comparison syntax][time]. ```plaintext created_at:>2weeks ``` ```plaintext created_at:<30minutes ``` ```plaintext updated_at:>1month ``` ```plaintext updated_at:2hours ``` ```plaintext suppressed_at:<1day ``` ## Attributes {#vulnerability-attributes} You can search all vulnerability attributes with the syntax `:`. This search term supports numerical comparison operators (`>`, `>=`, `<`, `<=`, `=`). If the attribute name conflicts with an existing term, the prefix `_vulnerability.` can be added to disambiguate the query. ```plaintext plugin.hasPatch:true ``` ```plaintext severityID:3 ``` ```plaintext _vulnerability.state:REOPENED ``` To determine if a vulnerability has any attribute defined, use the `has:` keyword. The `has` keyword can be inverted to find missing fields with `not has:`. ```plaintext has:plugin.vpr.score ``` ```plaintext not has:output ``` ## Certificate fields {#vulnerability-certificates} Certificate-related fields can be searched using the following keywords. ### Certificate ID {#vulnerability-certificate-id} Use the syntax `certificate_id:` to filter by certificate ID. ```plaintext certificate_id:4e3a2b1c-5d6f-7a8b-9c0d-1e2f3a4b5c6d ``` ### Certificate type {#vulnerability-certificate-type} Use the syntax `certificate_type:` to search by certificate type. ```plaintext certificate_type:"x509" ``` ### Certificate serial {#vulnerability-certificate-serial} Use the syntax `certificate_serial:` to search by certificate serial number. ```plaintext certificate_serial:"01A23B45C" ``` ### Certificate public key {#vulnerability-certificate-public-key} Use the syntax `certificate_public_key:` to search by certificate public key. ```plaintext certificate_public_key:"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..." ``` ### Certificate public key algorithm {#vulnerability-certificate-public-key-algorithm} Use the syntax `certificate_public_key_algorithm:` to search by certificate public key algorithm. ```plaintext certificate_public_key_algorithm:"ecPublicKey" ``` ### Certificate signature {#vulnerability-certificate-signature} Use the syntax `certificate_signature:` to search by certificate signature. ```plaintext certificate_signature:"abcdef1234567890" ``` ### Certificate signature algorithm {#vulnerability-certificate-signature-algorithm} Use the syntax `certificate_signature_algorithm:` to search by certificate signature algorithm. ```plaintext certificate_signature_algorithm:"rsaEncryption" ``` ### Certificate fingerprint (bkhash) {#vulnerability-certificate-bkhash} Use the syntax `certificate_fp_bkhash:` to search by certificate fingerprint (bkhash). ```plaintext certificate_fp_bkhash:"d2c7e8f9..." ``` ### Certificate fingerprint (SHA1) {#vulnerability-certificate-sha1} Use the syntax `certificate_fp_sha1:` to search by certificate SHA1 fingerprint. ```plaintext certificate_fp_sha1:"349eb7db55bbad9d7deabc5effdfd5521ed984a0" ``` ### Certificate fingerprint (SHA256) {#vulnerability-certificate-sha256} Use the syntax `certificate_fp_sha256:` to search by certificate SHA256 fingerprint. ```plaintext certificate_fp_sha256:"SHA256:Sc0pLUCvlNaGtu4Xy2fOTe1A6cC+KyU3x7xuN8+aLtA=" ``` ### Certificate subject {#vulnerability-certificate-subject} Use the syntax `certificate_subject:` to search by certificate subject. ```plaintext certificate_subject:"CN=example.com,O=ExampleCorp,C=US" ``` ### Certificate common name (CN) {#vulnerability-certificate-cn} Use the syntax `certificate_cn:` to search by certificate common name. ```plaintext certificate_cn:"example.com" ``` ### Certificate issuer {#vulnerability-certificate-issuer} Use the syntax `certificate_issuer:` to search by certificate issuing authority. ```plaintext certificate_issuer:"CN=Example CA,O=Example Corp,C=US" ``` ### Certificate subject key ID {#vulnerability-certificate-subject-key-id} Use the syntax `certificate_subject_key_id:` to search by certificate subject key ID. ```plaintext certificate_subject_key_id:"1234567890abcdef" ``` ### Certificate authority key ID {#vulnerability-certificate-authority-key-id} Use the syntax `certificate_authority_key_id:` to search by certificate issuing authority key ID. ```plaintext certificate_authority_key_id:"abcdef1234567890" ``` ## Suppression {#suppressed-vuln} The current suppressed or unsuppressed state of vulnerabilities can be searched using the syntax `suppressed:`. ```plaintext suppressed:t ``` will search for vulnerabilities that are suppressed. Inversely, ```plaintext suppressed:f ``` will search for vulnerabilities that are not suppressed. A special value of `any` can be used to display all records, regardless of suppression settings: ```plaintext suppressed:any ``` will display both suppressed and unsuppressed vulnerabilities. Additionally, the user who performed the suppression can be found using the following syntaxes: ```plaintext suppressed_by: ``` --- docs/search-query-certificates.md --- title: "Certificate inventory" --- When viewing certificates, you can use the following keywords to ((search|search certificates)) and filter. ## General certificate fields ### Certificate ID {#certificates-ID} The ID field is the unique identifier for a given certificate, written as a UUID. Use the syntax `id:` to filter by ID field. ```plaintext id:21e5252d-a6a5-467e-83ed-683657412dff ``` ### Certificate type {#certificates-type} Use the syntax `type:` to search for certificates by type. ```plaintext type:x509 ``` ### Name {#certificates-name} Use the syntax `name:` to search for certificates by name. ```plaintext name:example.com ``` ### Validity {#certificates-validity} Use `valid_from: