Skip to content

Commit

Permalink
Merge pull request #138 from IBM/develop
Browse files Browse the repository at this point in the history 
Pr for 2.8.1 release
  • Loading branch information
@omkar-g
omkar-g authored Oct 18, 2023
2 parents 41f9c24 + e2b2ead commit e146543
Show file tree
Hide file tree
Showing 19 changed files with 1,052 additions and 33 deletions.
104 changes: 104 additions & 0 deletions connectors/atp/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,110 @@ II. PREREQUISITES:
-----------------------------------------------------------------
Python == 3.5.x (greater than 3.5.x may work, less than probably will not; neither is tested)

The following permissions are required for the Microsoft Defender for Endpoint Connected Assets and Risk connector.

**Microsoft Graph**
* User.Read
* User.Read.All

**WindowsDefenderATP**
* AdvancedQuery.Read
* AdvancedQuery.Read.All
* Alert.Read.All
* Alert.ReadWrite.All
* Machine.Read
* Machine.Read.All
* Machine.ReadWrite
* Machine.ReadWrite.All
* User. Read.All

The API access requires OAuth2.0 authentication.

Generate an ATP access token by completing the following steps.
1. Create an Azure Active Directory application.
2. Get an access token that uses this application. Use the token to access the Microsoft Defender for Endpoint API.

For more information, see [Create an app to access Microsoft Defender for Endpoint without a user](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/api/exposed-apis-create-app-webapp?view=o365-worldwide).


The Microsoft Defender for Endpoint connector is designed to work with the api/advancedqueries/run, api/machines, and api/alerts API endpoints. For more information about these API endpoints, see [Supported Microsoft Defender for Endpoint APIs](https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide).

Microsoft Defender for Endpoint is an endpoint security platform to prevent, detect, investigate, and respond to advanced threats. For more information about Microsoft Defender for Endpoint, see [Microsoft Defender for Endpoint](https://www.microsoft.com/en-us/microsoft-365/windows/microsoft-defender-atp).

The Microsoft Defender for Endpoint schema is made up of multiple tables that provide either event information or information about devices and other entities. To effectively build queries that span multiple tables, you must understand the tables and the columns in the schema.

The following table outlines Microsoft Defender for Endpoint schema table names and descriptions.

| Table name | Description |
| :----------:|:---------------:|
| [AlertEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-alertevents-table) | Alerts on Microsoft Defender Security Center |
| [MachineInfo](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-machineinfo-table) | Machine information, including OS information |
| [MachineNetworkInfo](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-machinenetworkinfo-table) | Network properties of network devices, including adapters, IP addresses, MAC addresses, connected networks, and domains |
| [ProcessCreationEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-processcreationevents-table) | Process creation and related events |
| [NetworkCommunicationEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-networkcommunicationevents-table) | Network connection and related events |
| [FileCreationEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-filecreationevents-table) | File creation, modification, and other file system events |
| [RegistryEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-registryevents-table) | Creation and modification of registry entries |
| [LogonEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-logonevents-table) | Sign-ins and other authentication events |
| [ImageLoadEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-imageloadevents-table) | DLL loading events |
| [MiscEvents](https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-miscevents-table) | Multiple event types, including events that are triggered by security controls such as Windows Defender Antivirus and Exploit Protection |

The following table shows the Connected Assets and Risk connector to Machine Network Profile data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| IPAddress (Private) | _key | Machine NetworkInfo -> IPAddresses |
| IPAddress (Public) | _key | Machine Info -> PublicIP |
| MacAddress | _key | Machine NetworkInfo -> MacAddress |
| IPAddress_MacAddress | _from | ipaddress/_key(ipaddress node) |
| | _to | macaddress/_key(macaddress node) |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |
| Asset_IPAddress | from_external_id | external_id of the asset |
| | _to | ipaddress/_key(ipaddress node) |
| | active | TRUE |
| | timestamp | Activity log -> eventTimestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Users data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| User | _key | User -> accountName |
| Asset_User | from_external_id | Machine -> id |
| | _to | 'user/' + user -> accountName |
| | active | TRUE |
| | timestamp | Activity log -> eventTimestamp |
| | source | source -> _key |
| | report | report -> _key |
| User_Hostname | _from | 'user/' + user -> accountName |
| | _to | hostname/' + Machine -> computerDnsName |
| | active | TRUE |
| | timestamp | Activity log -> eventTimestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Vulnerabilities data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| Asset | Name | Machine -> computerDnsName |
| | Description | Custom message with: osPlatform |
| | external ID | Machine -> id |
| Vulnerability | external ID | Alerts -> id |
| | name | Alerts -> title |
| | Description | Alerts -> description |
| | disclosed_on | Alerts -> firstEventTime |
| | published_on | Alerts -> alertCreationTime |
| Asset_Vulnerability | from_external_id | external_id of the machine |
| | to_external_id | Alerts -> id |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |

III. INSTALLATION:
-----------------------------------------------------------------
`adal`
Expand Down
121 changes: 121 additions & 0 deletions connectors/azure/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,127 @@ II. PREREQUISITES:
-----------------------------------------------------------------
Python == 3.5.x (greater than 3.5.x may work, less than probably will not; neither is tested)

The following permissions are required for the Microsoft Azure Connected Assets and Risk connector.

**Azure Service Management**
* user_impersonation

**Microsoft Graph**
* PrivilegedAccess.Read.AzureResources
* PrivilegedAccess.ReadWrite.AzureResources
* SecurityActions.Read.All
* SecurityActions.ReadWrite.All
* SecurityEvents.Read.All
* SecurityEvents.ReadWrite.All
* User.Read

The Microsoft Azure Security Center connector is designed to work with the Virtual Machines, Network Interfaces, Applications, SQL databases, and Vulnerabilities resources.

Microsoft Azure Security Center is an infrastructure security management system that offers threat protection across hybrid cloud environments. For more information, see [Azure Security Center](https://azure.microsoft.com/en-us/services/security-center/).

The following table shows the Connected Assets and Risk connector to Virtual Machine data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| Asset | Name | VM Resource -> Name |
| | Description | "VM Image details:" VM Resource -> properties -> storageProfile -> imageReference - > Offer,Sku |
| | external ID | VM Resource -> id |
| Hostname | _key | Network Resource -> properties -> ipConfigurations -> properties -> fqdn |
| | Description | Custom Desc |
| Asset_Hostname | from_external_id | Network Resource -> properties -> virtualMachine -> id |
| | _to | Network Resource -> properties -> ipConfigurations -> properties -> fqdn |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Network Profile data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| IPAddress (Private) | _key | Network Resource -> properties -> ipConfigurations -> privateIPAddress |
| IPAddress (Public) | _key | Network Resource -> properties -> ipConfigurations -> publicIPAddress |
| MacAddress | _key | Network Resource -> properties -> macAddress |
| IPAddress_MacAddress | _from | ipaddress/_key(ipaddress node) |
| | _to | macaddress/_key(macaddress node) |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |
| Asset_IPAddress | from_external_id | external_id of the asset (based on resource type) |
| | _to | ipaddress/_key(ipaddress node) |
| | active | TRUE |
| | timestamp | Activity log -> eventTimestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Application data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| Application | _key | App Resource -> Name |
| | Name | App Resource -> Name |
| | Description | App Resource -> Name, Type, Location |
| | external ID | App Resource -> id |
| Asset_Application | from_external_id | Asset(Application) -> id |
| | to_external_id | App Resource -> id |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |
| Asset_ipaddress | from_external_id | Asset(Application) -> id |
| | _to | App Resource -> inboundIpAddress |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |
| Asset_hostname | from_external_id | Asset(Application) -> id |
| | _to | App Resource -> properties -> hostNames |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Database data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| Database | _key | DB Resource -> name |
| | Name | DB Resource -> name |
| | Description | DB Resource -> name , location |
| | external ID | DB Resource -> id |
| Asset_Database | from_external_id | Server Resource -> id |
| | to_external_id | DB Resource -> id |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |
| Asset_hostname | from_external_id | Server Resource -> id |
| | _to | DB Resource -> properties -> fullyQualifiedDomainName |
| | active | TRUE |
| | timestamp | report -> timestamp |
| | source | source -> _key |
| | report | report -> _key |

The following table shows the Connected Assets and Risk connector to Vulnerabilities data mapping.

| CAR vertex/edge | CAR field | Azure field |
| :------------:|:---------------:|:-----:|
| Asset | Name | VM Resource -> Name |
| | Description | "VM Image details:" VM Resource -> properties -> storageProfile -> imageReference - > Offer,Sku |
| | external ID | VM Resource -> id |
| Vulnerability | external ID | Security log -> eventDataId |
| | name | Security log -> eventName -> value |
| | Description | Security log -> description |
| | disclosed_on | Security log -> submissionTimestamp |
| | published_on | Security log -> eventTimestamp |
| Asset_Vulnerability | from_external_id | external_id of the asset (based on resource type) |
| | to_external_id | Security log -> eventDataId |
| | active | TRUE |
| | timestamp | Security log -> eventTimestamp |
| | source | source -> _key |
| | report | report -> _key |

III. INSTALLATION:
-----------------------------------------------------------------
`adal`
Expand Down
97 changes: 97 additions & 0 deletions connectors/crowdstrike/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,103 @@ II. PREREQUISITES:
-----------------------------------------------------------------
Python == 3.9.7 (greater than 3.9.x may work, less than probably will not; neither is tested)

**CrowdStrike Falcon - Asset & Vulnerability**

| FalconPy module | Method Name | Usage |
| :------------: | :------------:| :----------:|
| Discover | get_hosts( ) | Get details on Assets |
| | get_accounts( ) | Get details on Accounts |
| | get_applications( ) | Get details on Applications |
| Spotlight | get_vulnerabilities( ) | Get details on Vulnerabilities |

**Authentication:**

Users with the Falcon Administrator role can create new API clients from the API Clients and Keys page of the console.

Steps to create an API client:
1. Create API clients to grant various levels of API access for different purposes.
2. On the API Clients and Keys page (Support and resources > Resources and tools > API Clients and Keys), click Create API client.
3. Enter details to define your API client:
4. Client Name (required)
5. Description (optional)
6. API Scopes (required)
7. Select the Read and/or Write boxes next to a scope to enable access to its endpoints.
8. At least one scope must be assigned.
9. Click Create to save the API client and generate the client ID and secret.

**Mappings**

The following table shows the Connected Assets and Risk connector to Falcon Discover Asset Response data mapping.

| CAR vertex/edge | CAR field | Data source field |
| :------------: | :------------:| :----------:|
| Asset | name | Host -> hostname |
| | external_id | Host -> id |
| | asset_type | Host -> form_factor |
| | description | Host -> Product_type_desc |
| hostname | host_name | Host -> hostname |
| | _key | Host -> hostname |
| ipaddress | _key | Host -> external_ip OR Host -> network_interfaces -> local_ip |
| | regin_id | Host -> city, country |
| macaddress | _key | Host -> network_interfaces -> mac_address |
| | interface | Host -> network_interfaces -> interface_alias |
| geolocation | external_id | Host -> city, country |
| | region | Host -> city, country |
| asset_hostname | _from_external_id | Host -> id |
| | _to | Host -> hostname |
| asset_geolocation | _from_external_id | Host -> id |
| | _to_external_id | Host -> city, country |
| asset_ipaddress | _from_external_id | Host -> id |
| | _to | Host -> external_ip OR Host -> local_ip_addresses |
| asset_macaddress | _from_external_id | Host -> id |
| | _to | Host -> network_interfaces -> mac_address |
| ipaddress_macaddress | _from | Host -> external_ip OR Host -> local_ip_addresses |
| | _to | Host -> network_interfaces -> mac_address |
| ipaddress_geolocation | _from | Host -> external_ip OR Host -> local_ip_addresses |
| | _to_external_id | Host -> city, country |
| ipaddress_hostname | _from | Host -> external_ip OR Host -> local_ip_addresses |
| | _to | Host -> hostname |

The following table shows the Connected Assets and Risk connector to Falcon Discover Application Response data mapping.

| CAR vertex/edge | CAR field | Data source field |
| :------------: | :------------: | :----------:|
| application | name | App -> name OR App -> host -> os_version |
| | external_id | App -> id OR App -> host -> os_version + kernal_version |
| | is_os | False OR True |
| | owner | App -> vendor |
| | last_access_time | App -> last_updated_timestamp |
| asset_application | _from_external_id | Host -> id |
| | _to_external_id | App -> id OR App -> host -> os_version + kernal_version |

The following table shows the Connected Assets and Risk connector to Falcon Discover Account Response data mapping.

| CAR vertex/edge | CAR field | Data source field |
| :------------: | :------------: | :----------:|
| user | username | Account -> username |
| | external_id | Account -> username |
| account | name | Account -> account_name |
| | external_id | Account -> id |
| user_account | _from_external_id | Account -> username |
| | _to_external_id | Account -> id |
| asset_account | _from_external_id | Host -> id |
| | _to_external_id | Account -> id |

The following table shows the Connected Assets and Risk connector to Spotlight Vulnerability data mapping.

| CAR vertex/edge | CAR field | Data source field |
| :------------: | :------------: | :----------: |
| vulnerability | name | vulnerability response -> cve -> id |
| | external_id | vulnerability response -> id |
| | description | vulnerability response -> cve -> description |
| | base_score | vulnerability response -> cve -> base_score |
| | xfr_wx | vulnerability response -> cve -> exploitability_score |
| | published_on | vulnerability response -> cve -> published_date |
| asset_vulnerability | _from_external_id | Host -> id |
| | _to_external_id | vulnerability response -> id |
| application_vulnerability | _from_external_id | App -> id |
| | _to_external_id | vulnerability response -> id |

III. INSTALLATION:
-----------------------------------------------------------------
- Requirements.txt file attached.
Expand Down
2 changes: 1 addition & 1 deletion connectors/crowdstrike/requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
car-connector-framework==4.0.0
urllib3==1.26.15
urllib3==1.26.17
crowdstrike-falconpy==1.2.15
pytest==7.2.2
Loading

0 comments on commit e146543

Please sign in to comment.