runZero 201 training

Prerequisites

Before you start this training, we have two recommendations:

1. Superuser access to a runZero account. This can be a corporate account with a paid license, or a community account created with a personal email, which makes you the superuser.
2. Completion of the runZero 101 training, so you have the context behind the administrative actions this training covers.

Introduction to the training

This video briefly introduces what you will learn in this training.

Self-hosting

You can self-host runZero. The self-hosted version is identical to the SaaS version apart from a couple of edge cases, such as the runZero Hosted explorers not being available.

Self-hosting must be explicitly enabled on your runZero account. Contact your runZero sales representative for details.

Deployment planning

The demo below walks through deployment planning; the written version follows.

1. Hardware requirements 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 support covers 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, the server needs 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 are listed below.

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

4. Offline mode deployment is also possible, but updates become a manual process. See offline mode.

Setup

The demo below walks through self-hosted setup; the written version follows.

1. Installation

   • The runZero installation is a single command from your runZero SaaS console.
   • Download it from the console, assuming self-hosting is enabled on your account.
   • The self-hosting documentation has more detail on this step.

2. Post installation

   • Once the console is installed, create your admin user and log in with this command: runzeroctl initial <email>
   • The self-hosting documentation has more detail on this step.

3. Using your own PostgreSQL database

   • You can run the console and database on separate servers if you’d like to scale your workload horizontally.
   • The self-hosting documentation has more detail on this step.

4. Advanced configuration

   A few other common customization options:

   • Email Server (for Alerting and User Invites)
   • TLS Certificates
   • Hostname
   • The self-hosting documentation has more detail on these options.

5. Logging

   • Self-hosted runZero logs to the standard journalctl to simplify capturing data.
   • View logs with this sample command: journalctl --unit=runzero-console --since=-1hour --reverse

Using runzeroctl

The runzeroctl CLI handles most actions you need, such as starting or stopping the service and creating the initial user.

A few common commands:

• Restart the service: runzeroctl restart
• Update the platform and scanners: runzeroctl update [--force]
• Reset a user’s password and MFA: runzeroctl user reset <email>
• The self-hosting documentation has more detail on the CLI.

Initial configurations

This section covers the basics of configuring runZero: user management and data architecture.

Users

The demo below walks through the users section; the written version follows.

All user management happens under the Your team tab in the left navigation, which has 5 sub options:

1. Users shows all users in the current client account.
2. Restricted lists users who have access to only a single organization.
3. Your Organization Name lists users who have access to the organization you are currently using.
4. External lists users whose authentication happens on a different runZero client account but who have access to at least one organization in your current account.
5. Groups lists the available user groups. Groups define the access and permissions users have within each organization.

Adding users:

1. Click the tab for the user type you’d like to create, such as External or Restricted.

2. Two options appear at the top right: Invite users and Import users.

   • Invite: provide an email, set the access level, and optionally edit the email invitation.
   • Import: runZero can bulk create users from a CSV import. First name, Last name, and Email are required. Permissions are optional, and users default to the least permissions possible if none are provided.

3. Manage SSO from the first Users tab by clicking SSO Settings.

   • SSO modes

     1. Disabled: SSO is 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 information you need to create the runZero application in your service provider when you click Service Provider Information.
     2. Read more about implementing SSO for specific service provider documentation.

   • SSO group mappings

     1. You can create SSO group mappings in runZero to set permissions.
     2. These settings apply only after the next sign-out, and you can force sign-outs through the console.
     3. If multiple SSO group mappings match, the highest privilege mapping takes precedence.

Organizations and Projects

The demo below walks through organizations and projects; the written version follows.

1. Organizations are how runZero handles RBAC. To segment users’ visibility into sets of assets, put the assets 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 has an All Organizations view that searches the inventories of all the Organizations they have access to at once.

2. Projects are for short-term engagements. They go read-only after 30 days and are deleted automatically after 90 days.

Sites

The demo below walks through the sites section; the written version follows.

1. Sites primarily represent networks with overlapping IP space, rather than physical locations.
2. Use one Primary site unless you have overlapping IP space.
3. Each site has a set of subnets, and you can apply tags to them.
4. You can also import a CSV of subnets to create your sites.

Managing tasks

Tasks are how you get data into runZero, and they come in three primary types:

1. Active scan
2. Passive traffic sampling
3. Integration connections

This section covers the ways you can schedule these tasks to run.

Explorers

The demo below walks through the explorers section; the written version follows.

Explorers are primarily for active scanning and passive traffic sampling, but you can also run every integration connection from an explorer.

Installation

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. Supported operating systems

   • The explorer installs on macOS and most Linux or Windows operating systems.
   • See the full list of supported operating systems.

3. Installation

   • Go to the Deploy tab in the UI to get your unique explorer download link.
   • Select your OS type and follow the instructions.

4. Verify connectivity

   • Once installed, your explorer checks in to the Console and shows Online.
   • You can see your explorers in the console.

Configuration

1. Click the explorer name on the View explorers page to see its configuration options, and click the Edit button at the top of the page to update them.

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 scanning the wrong site by accident.

3. Concurrent tasks

   • Explorers with Linux-based operating systems (including macOS) can perform multiple tasks at once.
   • We recommend 1-4 concurrent tasks for most scenarios.
   • For a large scan like an RFC1918 scan, avoid running multiple tasks at the same time.

4. Tags

   • Tags you apply to an explorer are added to every asset discovered with it.

5. Passive traffic sampling

   • The options to enable passive traffic sampling are also on this page.
   • Discovery starts once you pick the interfaces to listen on, the site to associate the assets with, and the discovery scope.
   • Passive tasks start in 5 minute increments and adjust dynamically to the traffic volume the explorer sees.
   • Passive traffic sampling limits itself to a single core, so you don’t need to worry about resources.
   • That works because the explorer listens only for the subset of traffic useful for asset discovery, and drops any traffic it can’t process.

Explorer details page

1. System details

   • Every explorer reports basic info like Executable path, PID, and Memory usage.
   • This can be a helpful first step in diagnosing issues, rather than SSH-ing into the host.

2. Tasks

   • This page also lists every task the explorer has performed.
   • source:runzero shows active scans
   • source:sample shows passive traffic sampling tasks

3. Diagnostics

   • Explorer diagnostics are captured as needed.
   • Trigger a new capture by clicking Update diagnostics.

Credentials

The demo below walks through the credentials section; the written version follows.

1. Manage all credentials for SNMP and integrations on the Scanning with credentials page.
2. Click Add credential to select the credential type; the form then asks for what that type needs.
3. Setting a credential as Global lets all users use it in every Organization.
4. In most cases, you will limit a credential to a specific Organization.

Tasks

runZero has four pages for managing tasks, depending on what you are trying to do:

1. Tasks is the hub for tasks of all types. You can search all of your tasks here and configure any type, 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 shows all the active scans you have run so far, and you can configure new active scans on this page.

3. Monitor shows all the passive tasks that have run so far, and you can configure new passive traffic sampling tasks or import PCAPs on this page.

4. Integrate lists the supported integrations and lets you configure them.

Configuring an active scan

The demo below walks through the active scan section; the written version follows.

1. Go to Tasks and click Scan > to configure an active scan.

   • A Standard scan provides the full suite of configuration options.
   • A Template scan uses a pre-configured scan template, so you can manage configurations across many tasks at once. Some parts, like the discovery scope, remain editable per task.
   • An RFC1918 scan scans the entire RFC1918 space with minimal configuration, such as the packets per second and subnet sampling rate.
   • See more information on subnet sampling.

2. Configuration options

   • In most cases, you only need to update the options on the Standard tab of your scan configuration.

   • The commonly updated options:

     1. Site should ideally be a single Primary site for all assets, but you may have reason to use multiple sites.

     2. Explorer or Hosted zone picks between your locally deployed runZero explorers and Hosted zones, the runZero cloud-hosted explorers. You can use Hosted zones to scan public IP ranges and domains. Change explorer to None to select a Hosted zone.

     3. Scan rate caps the explorer’s packets per second. It defaults to 1000 but can usually be increased in most networks.

     4. Discovery scope set to defaults uses the site’s subnets configured at the site level. You can also enter IP ranges or domains, or populate the scope dynamically from your inventory with keywords like public:all.

        • See more about discovery keywords.

     5. Schedule runs scans hourly, daily, weekly, and so on, based on your needs.

     6. Scheduling grace period tells the task how long to wait if the explorer is already in use. If multiple tasks run on the same explorer, setting this to 0 can help avoid tasks failing because the explorer is already in use.

   • See advanced scan configurations for the other options.

Configuring passive traffic sampling

The demo below walks through passive traffic sampling; the written version follows.

1. This was covered earlier in the section on managing explorers, so the information here is a repeat.

2. Go to the explorer you want to configure passive traffic sampling on and follow these steps:

   • The options to enable passive traffic sampling are on this page.
   • Discovery starts once you pick the interfaces to listen on, the site to associate the assets with, and the discovery scope.
   • Passive tasks start in 5 minute increments and adjust dynamically to the traffic volume the explorer sees.
   • Passive traffic sampling limits itself to a single core, so you don’t need to worry about resources.
   • That works because the explorer listens only for the subset of traffic useful for asset discovery, and drops any traffic it can’t process.

Configuring an integration connection

The demo below walks through the integrations section; the written version follows.

1. Go to the Integrate page.

2. Find the integration you want and click Configure.

3. Create a new credential from the option in the form, or select an existing credential you created on the Credential page.

4. All integrations have these options:

   • Explorer lets any integration run from an explorer, which self-hosted services like Active Directory may need. In most cases, though, leave this as None to run directly from the Console.
   • Site is an optional backup site for assets that do not merge. Integration assets attempt to merge with assets in all sites in runZero. Here too, a single Primary site is highly recommended.

5. Depending on the integration, you will have additional options, all covered on that integration’s documentation page.

6. See the documentation about integrations.

Automated asset tracking

Once your asset discovery and integration tasks are configured, you can start keeping tabs on changes in your inventory in a few ways:

1. Queries are saved searches of your inventory that you can use to track how many assets or services of a specific type you have.
2. Goals are queries with targets for asset count or percentage and an optional time window.
3. Alerts trigger an activity like an email or webhook when your inventory has a match.
4. Asset ownership tracks who owns what, so you can skip pivots during investigations when you need to act on an asset.

The sections below cover each of these in detail.

Queries

The demo below walks through the queries section; the written version follows.

1. The Queries tab in runZero shows the out-of-the-box queries.

2. Each query shows a few attributes:

   • Name is a quick summary of what the search shows.
   • Matches is how many assets currently in your inventory match the query.
   • Severity is the level of impact if exposed.
   • Risk is the level of impact combined with the likelihood of exposure.
   • CVEs lists the CVEs related to this search.

3. You can search the Queries by these attributes as well. Two common searches:

   • High or critical risk with matches in the inventory: (risk:high or risk:critical) matches:>0
   • Queries with an associated CVE and matches in the inventory: cve:“CVE%” matches:>0

4. Click a query’s name to view its details.

5. The details show a description and the search string, and let you test the query.

6. Vulnerability settings let you create your own vulnerability records from the runZero queries. When there is a match, it shows up on the asset as well as in the vulnerability inventory.

7. To create a custom query, click Create query on the main Queries tab. You get the same options to fill in as the query details page showed. In most scenarios, we recommend matching only on live assets and testing the query before saving.

Goals

The demo below walks through the goals section; the written version follows.

1. Goals build on queries by letting you set targets for them. Beyond queries, you can also set goals for asset risk and ownership.

2. For example, you might set a goal on the SSH password authentication on internet-facing host query, meaning all of your internet-facing SSH services should require SSH keys.

3. To create a goal:

   • Click New goal on the Goals tab.
   • Pick the type that fits your goal: System query, Custom query, Asset risk, or Asset ownership.
   • Set Permissions to 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 the goal’s parameters.
   • For a query goal, pick your query and set the target asset count or percentage.
   • For a risk or ownership goal, set your target asset count or percentage.
   • Review and save your goal to start tracking it.
   • Once goals are configured, you can see their progress on the Goals tab, or on your dashboard if you chose to pin them there.

Alerts

The demo below walks through the alerts section; the written version follows.

1. The events tab lists most of the events that can trigger alerts in runZero.

2. Creating an Alert requires three main steps:

   • Create a template for the alert to use, either JSON or Email.
   • Create a channel for the alert to go to, either an Email address or an HTTPS webhook.
   • Create a rule for the trigger conditions to watch.
   • For more detailed instructions, follow the playbook on creating alerts on asset and service changes.

3. If the alert does not need to go to an external system, you can create a rule that triggers a local alert in runZero instead. Local alerts appear on the alerts tab.

4. Beyond monitoring your inventory, rules can update your assets automatically based on what you know about your environment.

5. For example, to set Asset Ownership on a set of assets:

   • Click Create rule.
   • Name the rule, select asset-query-results from the event list, and configure organization access. Then click next.
   • Enter your query to identify the assets you want to update.
   • Set number of matches to is greater than 0.
   • Optionally set the site, explorer, or task type if you do not want the rule triggered on all events. Click next.
   • Change the action to Modify asset.
   • Set the Ownership values of interest.

6. The full list of asset values that rules can update:

   • 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 walks through the asset ownership section; the written version follows.

1. Asset ownership in runZero tracks 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 the alerts section above for an example)
   • Manually through the Inventory or Asset detail pages

3. Superusers can set ownership types on the Ownership tab.

   • Assets can have up to 10 ownership types, for flexibility based on your environment.

   • The Asset owner is the default owner that integrations populate.

   • Add more types by clicking the Add ownership type button.

   • For each type, you set a name, an optional reference, and whether it is hidden or visible to users.

   • Reference options:

     1. None means the ownership value can be anything.
     2. Directory user or group provides a dropdown while updating ownership, limited to Active Directory data.
     3. runZero user or group provides a dropdown while updating ownership, limited to runZero users or groups.

4. Once types are configured, all users can set the ownership types on assets based on that configuration.

5. You can search assets by ownership in a few ways:

   • Asset has an owner: has_owner:t
   • Owner is named Tyler: owner:tyler
   • Owner count is greater than or equal to 2: owner_count:>2
   • Owner type IT is known: owner:it

Using the API

With the runZero API, you can export your inventory data, extend functionality, and automate processes.

Authentication options

The demo below walks through the authentication options section; the written version follows.

Depending on the use case, you can authenticate to the runZero API in a few ways:

1. Account level access

   • API clients use Client ID and Secret authentication. They have full read/write access to the entire account and can perform any action via the API.
   • Account API keys use HTTP Basic authentication. They have full read/write access to the entire account and can perform any action via the API.

2. Organization level access

   • To create Organization level access tokens, go to Organizations, click the organization of interest, and click Edit organization.
   • Organization API tokens have full read/write access to the Organization and can perform any action via the API on that specific Organization.
   • Export tokens are read-only tokens for exporting inventory data from runZero. They are the most commonly used token, since exporting data is the most common use case.
   • Download tokens allow automated explorer deployments. Their only access is downloading the explorer binary for installation on a host.

Common use cases

Each use case below lists the relevant API endpoints and sample scripts.

Exporting inventory

1. Use case

   • Customers commonly want their inventory data populated elsewhere, like a SIEM or CMDB, for other teams to consume downstream.
   • runZero has native integrations for tools like Splunk and ServiceNow, and customers have integrated with plenty of other tools as well.

2. API endpoints

   • Asset inventory, JSON format. Other format options include JSONL, CSV, and XML.
   • Service inventory, JSON format. Other format options include JSONL and CSV.
   • Vulnerability inventory, JSON format. 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
   • Export and transform to CSV
   • Export and stream to PowerBI

Scan task scheduling

1. Use case

   • If your SOAR is hooked up to runZero, you may want to search the inventory for specific IP addresses, hostnames, and so on.
   • If the search returns nothing, you may want to trigger a scan.

2. API endpoints

   • To run the search, use the export endpoints above.
   • To run the scan, use the scan endpoint.

3. Sample script

   • Search results or scan

Custom integrations

1. Use case

   • Many customers have inventory data in tools that runZero’s native integrations do not currently support.
   • For those, runZero supports Custom Integrations.
   • You connect to your other sources, transform the data to the runZero data model, and upload it to merge with your runZero inventory.

2. API endpoints

   • View custom integrations
   • Create new custom integration
   • Upload custom integration data and create task to process

3. Sample scripts

   • Tanium
   • Cylance
   • JAMF