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 treated as workflows, but they are not available from the Workflows page nor are they accessible as an action from Assets or Queries.
- Profiles - Allows for connecting additional logins and instances to the same connector.
- 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 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). |
| Settings | Displays the connector settings per profile. Check out Manage your connectors for more information. |
| Releases | Displays a summary of recent releases for the connector. |
| 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. |
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, with numbers closer to 1.0 being more correlated to similar types).
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 with data available.
Manage your connectors
After the initial connector installation, you may need to update credentials, add or remove profiles, or adjust import feeds. For additional information on managing import feeds, visit Manage your import feeds.
Managing profiles may require connector update first
If a connector supports profiles, it may need to be updated first before you can add, edit, or remove profiles.
To update credentials:
- From the Command Platform, navigate to Surface Command > Connectors.
- Click the connector that needs updated.
- Click Settings.
- Next to a profile, click Edit.
- Update the fields across the tabs as necessary.
- Click Save.
To add a profile:
- From the Command Platform, navigate to Surface Command > Connectors.
- Click the connector that needs updated.
- Click Settings.
- Click + Profile.
- Fill the fields as necessary.
- Click Save.
To test a profile:
Some connectors support testing a profile's credentials to ensure it's configured properly.
- From the Command Platform, navigate to Surface Command > Connectors.
- Click the connector that needs updated.
- Click Settings.
- Click Test Connection. A message reports any errors found.
Manage your import feeds
Most connectors have at least one import feed that controls 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 one profile. 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 can be managed from the Import Feeds page or from the Edit Profile window. You can schedule the import feeds for a connector differently in each profile. You can only schedule import feeds for connectors that are turned on.
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. Click the import feed then History to see the list of jobs. Expand a job to get details on the failure.
To add or edit a schedule on the Import Feeds page:
- 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.