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 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

runZero allows for self-hosting. 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

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 - you can deploy in 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 here assuming you have it enabled in your account.
   • Additional details for this part of the setup can be found in our online documentation pages here.

2. Post installation

   • Once the console is installed, you can create your admin user and login with this command runzeroctl initial <email>
   • Additional details for this part of the setup can be found in our online documentation pages here.

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 here.

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 here.

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

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 <email>
• Additional details for this part of the setup can be found in our online documentation pages here.

Initial configurations

This section will cover the basics for getting runZero configured. It will cover user management and data architecture.

Users

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. Note: we generally recommend keeping a single local account for break glass situations, but support can also assist if needed.

   • Service provider settings

     1. runZero provides the necessary information to create the runZero application in your service provider if you click Service Provider Information.
     2. More here 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 through the console.
     3. If multiple SSO group mappings match, the highest privilege mapping will take precedence.

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

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 to create your sites here.
5. 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

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 here.

3. Installation

   • You will navigate to the Deploy tab 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 here.

Configuration

1. Click the explorer name on the View 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

The demo below shows you a walkthrough of the credentials section. The written form can be found below the demo.

1. The 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

There are four pages for managing tasks in runZero depending on what you are trying to do:

1. Tasks 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 provides a view of all active scans you have done thus far, and you can configure new active scans on this page.

3. 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 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 > <Scan Type> to configure an active scan.

   • A Standard scan provides the full suite of configuration options
   • A Template scan 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 scans the entire RFC1918 space and allows minimal configuration like the packets per second and subnet sampling rate.
   • More on subnet sampling here.

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 on discovery keywords here.

     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.

   • If you are interested in more advanced scan configurations, there is more information here.

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.

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.

   • 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.

   • 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.

5. Depending on the integration, you will have additional options which are all documented on the documentation page for that integration.

6. Integration documentation can be found here.

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 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
   • Queries with an associated CVE with matches in the inventory - cve:“CVE%” matches:>0

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

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 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

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.

2. Creating an Alert requires three main steps:

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

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.

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
   • Select asset-query-results and click Configure rule
   • 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.

   • 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
   • 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

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 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 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, 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 - 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 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.

3. Sample script

   • Search results or scan

Custom integrations

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
   • Create new custom integration
   • Upload custom integration data and create task to process

3. Sample scripts

   • Tanium
   • Cylance
   • JAMF