Connectors
A Connector is the Surface Command component that interfaces with an information source to collect information about the assets in your environment. The Connector defines its own set of asset types to describe the structure of the data. An information source is an existing system or data source that has information about any object of interest. Common information sources include vulnerability scanning tools, endpoint protection technologies, and cloud infrastructure, such as AWS, Azure, and GCP. Each Connector is designed to understand the specifics of the targeted information source’s API and data schemas. Surface Command provides Connectors for all major security tools and can provide custom Connectors to meet the needs of your enterprise-specific system.
The data that the Connector ingests includes the asset’s properties and relationships to other assets. To keep the data current, Connectors periodically pull from their information source for new or changing situations. Surface Command then manages the data ingestion process, including correlation and mapping data from each Connector.
When you look at the details of a specific asset from a query results table, you can see the unified properties (review Workspace and queries for more information). The other tabs provide the data from the information sources as ingested by the Connectors. For more information about unified types and correlation, review Assets.
A Connector can include the following components:
- Import feeds - Collects data from an information source and execute operations on behalf of a Connector. A single Connector can have multiple import feeds. Import Feeds are Surface Command Workflows, but they are not available from the Workflows page nor are they accessible as an action from Assets or Queries.
- Data zones - Represents a defined area where the Connector operates, such as a specific network, physical location, or different countries.
- Workflows and functions - Interacts with external systems and executes actions. Actions can include performing further information enrichment or taking steps to remediate a problem. Workflows are also accessible from the Workflows page. Functions are available for use in other workflows.
Understand your Connectors
Regardless if a Connector has been set up, you can view information about it from the Connectors page in Surface Command.
To view all supported Connectors:
- Log in to the Command Platform.
- Click Surface Command.
- Click Connectors.
The Connectors page loads a list of Connector cards. Click any card to expand a side panel containing Connector details organized into tabs:
| Tab | Description |
|---|---|
| Summary | Displays summary information for the Connector, including version number, description, and Connector dependencies (other Connectors required for this Connector to be turned on). |
| Types | Displays extensive details about the asset types provided by Connector. Check out Connector Types for more information. |
| Queries | Displays any Queries installed with the Connector. |
| Workflows | Displays the Import Feeds and Workflows installed with the Connector. |
| Functions | Displays the functions installed with the Connector. |
| Settings | Displays the Connector settings per data zone. Check out Manage your Connectors for more information. |
Connector Types
A Connector stores data as provided by the information source, but it also maps the asset property names to any corresponding unified model property names called types. When type data is available for a Connector, each type shows the current number of assets ingested by the Connector. If the properties in the type were correlated, the type also displays the correlation score (0.0 to 1.0).
No data available?
Types with no data available do not have additional information. A type that provides no data might be a normal situation. However, you can check the Connector’s import feeds to verify that they have run. Visit Manage your Import Feeds for more information.
There are 2 kinds of properties:
Fulfilling properties
The property that is mapped to the unified model is called a fulfilling property. For example, the SentinelOne Connector ingests asset data that has a property lastActiveDate. The property is mapped to a unified property, endpoint_last_seen. Only those properties with a value are mapped to the unified model. Visit Assets for more details on the Unified Asset Model.
The Connector calculates a completeness score (0 to 100%) for the fulfilling properties. The completeness score is calculated from the following statistics:
- % populated - Percentage of the assets associated with the Connector that contributed to the individual property's completeness by populating it with a value.
- # distinct values - Number of distinct values for a property across the assets associated with the Connector. For example, the asset's name should be unique for each asset. If there are 10 assets, there should be 10 distinct values for asset name. Conversely, the asset's country might have less than 10 distinct values as assets may share a country.
Correlating properties
The property that represents the unified property across assets is called a correlating property. For example, the Driftnet Connector creates a unified property Driftnet Service that is the result of 2 correlating properties: Network Service Hostname:Port and Network Service IP:Port.
The correlation score is calculated from the following statistics:
- % populated - Percentage of the properties that have a value. These are the values that are correlated with properties from other Connectors.
- % unique - Percentage of properties values that occur once in the data. Less than 100% indicates duplicate values, which might cause over-correlation. Some properties are known to be not unique, for example, a MAC address value. Properties that are guaranteed not unique are excluded from correlation. Excluding these properties does cause the % unique value to be less than 100 but does not cause over-correlation.
Only properties that are correlated are included in the calculation. A low correlation score indicates that some of the Connector’s properties were not matched with those from other Connectors and could indicate a gap in security tool coverage. Otherwise, the correlating properties and scope are useful only in assessing the data quality of the source.
To view a type's fulfilling properties, correlating properties, statistics, and charts:
- From the Command Platform, navigate to Surface Command > Connectors.
- Click a Connector.
- Click the Types tab.
- Click a property.
Manage your Connectors
Rapid7 Support and Surface Command Deployment teams install Connectors for you, which includes creating data zones. After the initial installation, however, you may need to update Connector credentials or manage data zones. For information on managing Import Feeds, visit Manage your Import Feeds.
Add or update Connector credentials
If you need to add or update credentials for an installed Connector, you'll need to open the Connector details panel and edit the credentials for each data zone as necessary.
To add or update credentials:
- From the Command Platform, navigate to Surface Command > Connectors.
- Click the Connector that needs updated.
- Click Settings.
- Next to a data zone, click Edit.
- Update the fields as necessary.
- Click Save.
- Repeat as necessary for additional data zones or Connectors.
Add or manage data zones
You manage Connectors and their import feeds in the context of a data zone. A Connector is configured differently in each data zone. The configuration includes the following:
- Turn the Connector on or off
- Configure credentials and any other settings for the Connector. The Connector can connect to a different information source in each data zone.
- Schedule when the import feeds run, which pulls from the information source and updates the data.
To access the data zone configuration settings:
- From the Command Platform, navigate to Surface Command > Connectors.
- Click Manage zone settings. A side panel expands with tabs available for each data zone.
- Select a data zone tab.
From here, you can:
- See which Connectors are available for each data zone
- View, edit, or test credentials for a Connector
- Add a new data zone (data zones cannot be deleted)
- Turn on or off Connectors
Manage your Import Feeds
1 or more import feeds are associated with each installed Connector and control importing data from information sources. You may need to check the log history for an import feed or change its schedule.
View import feed details
You can view all import feeds by navigating to Surface Command > Import Feeds from the Command Platform. This page only shows import feeds from Connectors that are turned on in at least 1 data zone. Click an import feed to view details, including what Connector the import feed is associated with and a historical log.
Manage import feeds
Connectors and their import feeds are managed in the context of a data zone. You can schedule the import feeds for a Connector differently in each data zone. You can only schedule import feeds for Connectors that are turned on. To view all import feeds, navigate to Surface Command > Import Feeds from the Command Platform. On this page, you can view the schedule of the import feeds.
If there is an active instance of the import feed running, you have the option to stop it. If there are no active instances of the import feed, you have the option to run it now instead of waiting for the next scheduled event.
Last run failed?
A caution symbol next to the last run date indicates that the run was not successful. For information to obtain the log for a failed run, see Viewing import feed details.
To add or edit a schedule for an import feed:
- Search for an import feed.
- Click Edit (pencil icon).
- Set a time and frequency for the schedule. Alternatively, you can pause or remove an existing schedule from this window.
- Click Save.