Imp/update assets connectors doc

docs/integration/assets_categories/device/aws_ec2_device.md

@@ -135,6 +135,210 @@ To start getting your AWS EC2 instances into Sekoia.io, you need to create an as
 
 6. Click the **Create asset connector** button.
 
+## Information Collected
+
+The AWS EC2 asset connector fetches comprehensive EC2 instance information from AWS and transforms it into the OCSF (Open Cybersecurity Schema Framework) Device Inventory format for standardized security monitoring and asset management.
+
+### Data Mapping Table
+
+The following table shows how AWS EC2 instance data is mapped to OCSF model fields:
+
+| Source Field | OCSF Field Path | Description | Data Type |
+|--------------|-----------------|-------------|-----------|
+| `InstanceId` | `device.uid` | EC2 instance unique identifier | String |
+| `PublicDnsName` / `PrivateDnsName` | `device.hostname` | Public or private DNS name (fallback to instance ID) | String |
+| `Tags[Name]` | `device.name` | Instance name from Name tag | String |
+| `PlatformDetails` | `device.os.name` | Operating system name (Windows, Linux, MacOS) | String |
+| `PlatformDetails` | `device.os.type` | Operating system type enum | String (Enum) |
+| `PlatformDetails` | `device.os.type_id` | Operating system type ID (100=Windows, 200=Linux, 300=MacOS, 0=Unknown) | Integer (Enum) |
+| `NetworkInterfaces[].NetworkInterfaceId` | `device.network_interfaces[].uid` | Network interface unique identifier | String |
+| `NetworkInterfaces[].Description` | `device.network_interfaces[].name` | Network interface description | String |
+| `NetworkInterfaces[].MacAddress` | `device.network_interfaces[].mac` | MAC address | String |
+| `NetworkInterfaces[].PrivateIpAddress` | `device.network_interfaces[].ip` | Private IP address | String |
+| `NetworkInterfaces[].PrivateDnsName` | `device.network_interfaces[].hostname` | Private DNS name | String |
+| `NetworkInterfaces[]` | `device.network_interfaces[].type` | Interface type (always "Wired") | String (Enum) |
+| `NetworkInterfaces[]` | `device.network_interfaces[].type_id` | Interface type ID (always 1 for Wired) | Integer (Enum) |
+| `SecurityGroups[].GroupId` | `device.groups[].uid` | Security group ID | String |
+| `SecurityGroups[].GroupName` | `device.groups[].name` | Security group name | String |
+| `PublicIpAddress` / `PrivateIpAddress` | `device.ip` | Primary IP address (public preferred, fallback to private) | String |
+| `Placement.AvailabilityZone` | `device.region` | AWS availability zone | String |
+| `SubnetId` | `device.subnet` | Subnet ID | String |
+| `VpcId` | `device.domain` | VPC ID (mapped as domain) | String |
+| `Hypervisor` | `device.hypervisor` | Hypervisor type (e.g., xen, nitro) | String |
+| Static value | `device.vendor_name` | Always "Amazon Web Services" | String |
+| `InstanceType` | `device.model` | Instance type (e.g., t2.micro, m5.large) | String |
+| `LaunchTime` | `device.boot_time` | Instance launch time (ISO format) | String (ISO 8601) |
+| `BlockDeviceMappings[0].Ebs.AttachTime` / `LaunchTime` | `device.created_time` | Creation timestamp (Unix epoch) | Integer (timestamp) |
+| `IamInstanceProfile` | `device.is_managed` | Whether instance has IAM role (managed) | Boolean |
+| `Tags[aws:autoscaling:groupName]` | `device.autoscale_uid` | Auto Scaling group name | String |
+| `ImageId` + `State.Name` | `device.desc` | Description with AMI ID and state | String |
+| `Reservations[].OwnerId` | `device.org.uid` | AWS Account ID | String |
+| `Reservations[].OwnerId` | `device.org.name` | Organization name (e.g., "AWS Account 123456789012") | String |
+| Static value | `device.type` | Always "Server" | String (Enum) |
+| Static value | `device.type_id` | Always 1 (Server) | Integer (Enum) |
+| `LaunchTime` / `BlockDeviceMappings[0].Ebs.AttachTime` | `time` | Event timestamp for OCSF model (Unix epoch) | Integer (timestamp) |
+
+### OCSF Model Structure
+
+The connector generates OCSF Device Inventory events (class UID 5001) with the following structure:
+
+```json
+{
+  "activity_id": 2,
+  "activity_name": "Collect",
+  "category_name": "Discovery",
+  "category_uid": 5,
+  "class_name": "Device Inventory Info",
+  "class_uid": 5001,
+  "type_name": "Device Inventory Info: Collect",
+  "type_uid": 500102,
+  "severity": "Informational",
+  "severity_id": 1,
+  "time": "<unix_timestamp>",
+  "metadata": {
+    "product": {
+      "name": "AWS EC2",
+      "version": "<version>"
+    },
+    "version": "<ocsf_version>"
+  },
+  "device": {
+    "type": "Server",
+    "type_id": 1,
+    "uid": "<instance_id>",
+    "hostname": "<public_or_private_dns>",
+    "name": "<name_from_tags>",
+    "ip": "<public_or_private_ip>",
+    "os": {
+      "name": "Linux|Windows|MacOS|Unknown",
+      "type": "Linux|Windows|macOS|Unknown",
+      "type_id": 100|200|300|0
+    },
+    "network_interfaces": [
+      {
+        "uid": "<network_interface_id>",
+        "name": "<interface_description>",
+        "mac": "<mac_address>",
+        "ip": "<private_ip_address>",
+        "hostname": "<private_dns_name>",
+        "type": "Wired",
+        "type_id": 1
+      }
+    ],
+    "groups": [
+      {
+        "uid": "<security_group_id>",
+        "name": "<security_group_name>"
+      }
+    ],
+    "region": "<availability_zone>",
+    "subnet": "<subnet_id>",
+    "domain": "<vpc_id>",
+    "hypervisor": "<hypervisor_type>",
+    "vendor_name": "Amazon Web Services",
+    "model": "<instance_type>",
+    "boot_time": "<launch_time_iso>",
+    "created_time": <unix_timestamp>,
+    "is_managed": true|false,
+    "autoscale_uid": "<autoscaling_group_name>",
+    "desc": "AMI: <image_id>, State: <state>",
+    "org": {
+      "name": "AWS Account <account_id>",
+      "uid": "<account_id>"
+    }
+  }
+}
+```
+
+### Enrichment Objects
+
+The connector performs several enrichment operations to provide comprehensive device context:
+
+#### Network Interface Enrichment
+- **Source**: `NetworkInterfaces[]` array from EC2 instance data
+- **Enrichment**: Extracts detailed network interface information
+- **Fields added**: 
+  - `device.network_interfaces[]` with ID, description, MAC address, private IP, private DNS
+  - Always sets type as "Wired" (type_id: 1) for EC2 instances
+- **Special handling**: Continues on individual interface extraction errors
+
+#### Security Group Enrichment
+- **Source**: `SecurityGroups[]` array from EC2 instance data
+- **Enrichment**: Maps EC2 security groups to OCSF Group objects
+- **Fields added**: `device.groups[]` with security group ID and name
+- **Purpose**: Tracks network access control and firewall rules
+
+#### Operating System Detection
+- **Source**: `PlatformDetails` field from EC2 instance
+- **Enrichment**: Determines OS type from platform details string
+- **Logic**: 
+  - Searches for "windows" → Windows (type_id: 100)
+  - Searches for "linux" or "unix" → Linux (type_id: 200)
+  - Searches for "macos" or "mac" → MacOS (type_id: 300)
+  - Otherwise → Unknown (type_id: 0)
+- **Fields added**: `device.os.name`, `device.os.type`, `device.os.type_id`
+
+#### Hostname Resolution
+- **Source**: `PublicDnsName` and `PrivateDnsName` fields
+- **Enrichment**: Determines the best hostname for the device
+- **Priority**: 
+  1. Public DNS name (if available)
+  2. Private DNS name (if public not available)
+  3. Instance ID (if neither DNS name is available)
+- **Fields added**: `device.hostname`
+- **Special handling**: Empty strings treated as None
+
+#### Tag-Based Name Extraction
+- **Source**: `Tags[]` array with Key-Value pairs
+- **Enrichment**: Extracts the "Name" tag value
+- **Fields added**: `device.name`
+- **Purpose**: Provides human-readable instance names
+
+#### Auto Scaling Group Detection
+- **Source**: `Tags[]` array with Key-Value pairs
+- **Enrichment**: Extracts the "aws:autoscaling:groupName" tag
+- **Fields added**: `device.autoscale_uid`
+- **Purpose**: Identifies instances managed by Auto Scaling
+
+#### Organization Enrichment
+- **Source**: `OwnerId` from Reservation data
+- **Enrichment**: Creates organization object from AWS Account ID
+- **Fields added**: 
+  - `device.org.uid` (account ID)
+  - `device.org.name` (formatted as "AWS Account <account_id>")
+
+#### Management Status Detection
+- **Source**: `IamInstanceProfile` field
+- **Enrichment**: Determines if instance is managed based on IAM role presence
+- **Logic**: Instance is considered "managed" if it has an IAM instance profile attached
+- **Fields added**: `device.is_managed` (boolean)
+- **Purpose**: Identifies instances with automated management capabilities
+
+#### Primary IP Resolution
+- **Source**: `PublicIpAddress` and `PrivateIpAddress` fields
+- **Enrichment**: Determines the primary IP address
+- **Priority**:
+  1. Public IP address (if available)
+  2. Private IP address (if public not available)
+- **Fields added**: `device.ip`
+
+#### Creation Time Resolution
+- **Source**: `BlockDeviceMappings[0].Ebs.AttachTime` and `LaunchTime`
+- **Enrichment**: Determines the most accurate creation timestamp
+- **Priority**:
+  1. EBS attachment time (if available)
+  2. Launch time (as fallback)
+- **Fields added**: `device.created_time` (Unix timestamp), `time` (event timestamp)
+- **Special handling**: Ensures UTC timezone, converts to epoch timestamp
+
+#### Description Generation
+- **Source**: `ImageId` and `State.Name` fields
+- **Enrichment**: Creates a descriptive string combining AMI ID and instance state
+- **Format**: "AMI: <image_id>, State: <state>"
+- **Fields added**: `device.desc`
+- **Purpose**: Provides quick reference to instance image and current state
+
+
 ## Further Reading
 - [AWS EC2 Documentation](https://docs.aws.amazon.com/ec2/)
 - [AWS IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/)

docs/integration/assets_categories/device/crowdstrike_falcon_device.md

@@ -50,3 +50,156 @@ To start getting your CrowdStrike assets into Sekoia.io, you need to create an a
     ![Connector test result and Create asset connector button highlighted](/assets/operation_center/asset_connectors/device/crowdstrike_falcon/add_asset_device_asset.png)
 
 5. Click the **Create asset connector** button.
+
+## Information Collected
+
+This section describes the information fetched from CrowdStrike Falcon and how it maps to the OCSF (Open Cybersecurity Schema Framework) v1.6.0 Device Inventory Info model.
+
+### Data Mapping Table
+
+The following table shows how CrowdStrike Falcon device fields are mapped to OCSF fields:
+
+| CrowdStrike Source Field | OCSF Field Path | Description | Data Type |
+|--------------------------|-----------------|-------------|-----------|
+| `device_id` | `device.uid` | Unique device identifier | String |
+| `hostname` | `device.hostname` | Device hostname | String |
+| `product_type_desc` | `device.type_id`, `device.type` | Device type (Server, Workstation, Laptop, Mobile, Tablet) | Enum |
+| `platform_name` | `device.os.name` | Operating system name | String |
+| `os_version` | `device.os.version` | Operating system version | String |
+| `os_build` | `device.os.build` | Operating system build number | String |
+| `external_ip` | `device.ip` | External IP address of the device | String |
+| `local_ip` | `device.network_interfaces[].ip` | Local IP address | String |
+| `mac_address` | `device.network_interfaces[].mac` | Primary MAC address | String |
+| `connection_ip` | `device.network_interfaces[].ip` | Connection IP address | String |
+| `connection_mac_address` | `device.network_interfaces[].mac` | Connection MAC address | String |
+| `default_gateway_ip` | `device.subnet` | Default gateway IP address | String |
+| `system_manufacturer` | `device.hw_info.manufacturer` | Hardware manufacturer | String |
+| `system_product_name` | `device.hw_info.model` | Hardware model | String |
+| `bios_version` | `device.hw_info.bios_ver` | BIOS version | String |
+| `bios_manufacturer` | `device.hw_info.bios_manufacturer` | BIOS manufacturer | String |
+| `serial_number` | `device.hw_info.serial_number` | Device serial number | String |
+| `agent_version` | `device.agent_list[].version` | CrowdStrike Falcon agent version | String |
+| `cid` | `device.org.uid` | CrowdStrike Customer ID | String |
+| `service_provider` | `device.org.name` | Service provider name | String |
+| `machine_domain` | `device.domain` | Machine domain | String |
+| `ou` | `device.ou` | Organizational unit | String |
+| `first_seen` | `device.first_seen_time` | First time device was seen | Timestamp |
+| `last_seen` | `device.last_seen_time` | Last time device was seen | Timestamp |
+| `modified_timestamp` | `device.modified_time` | Last modification timestamp | Timestamp |
+| `agent_local_time` | `device.agent_list[].agent_time` | Agent local time | Timestamp |
+| `kernel_version` | `device.os.kernel_version` | Operating system kernel version | String |
+| `status` | `device.is_compliant` | Device compliance status (derived) | Boolean |
+| `reduced_functionality_mode` | `device.is_compliant` | Reduced functionality mode status | String |
+| `filesystem_containment_status` | `device.is_compliant` | Filesystem containment status | String |
+| `groups` | `device.groups[].name`, `device.groups[].uid` | Device groups | Array |
+| `device_policies.firewall` | `enrichments[].data.Firewall_status` | Firewall policy status | String |
+| `city` | `device.location.city` | Geographic location - city | String |
+| `country` | `device.location.country` | Geographic location - country | String |
+| `continent` | `device.location.continent` | Geographic location - continent | String |
+
+### OCSF Model Structure
+
+The connector generates OCSF Device Inventory Info events (Class UID: 5001) with the following structure:
+
+**Event Metadata:**
+- **activity_id**: 2 (Collect)
+- **activity_name**: "Collect"
+- **category_name**: "Discovery"
+- **category_uid**: 5
+- **class_name**: "Device Inventory Info"
+- **class_uid**: 5001
+- **type_name**: "Device Inventory Info: Collect"
+- **type_uid**: 500102
+- **severity**: "Informational" (severity_id: 1)
+
+**Device Object Structure:**
+```
+device:
+  - uid: Device unique identifier
+  - hostname: Device hostname
+  - type_id: Device type ID (enum)
+  - type: Device type string
+  - os: Operating system information
+    - name: OS name
+    - version: OS version
+    - build: OS build number
+    - type_id: OS type ID
+    - type: OS type string
+    - kernel_version: Kernel version
+  - ip: External IP address
+  - network_interfaces: Array of network interfaces
+    - hostname: Interface hostname
+    - ip: IP address
+    - mac: MAC address (normalized format)
+    - name: Interface name (e.g., "primary", "connection")
+  - subnet: Default gateway/subnet
+  - hw_info: Hardware information
+    - manufacturer: Hardware manufacturer
+    - model: Hardware model
+    - bios_ver: BIOS version
+    - bios_manufacturer: BIOS manufacturer
+    - serial_number: Serial number
+  - agent_list: Array of agent information
+    - type: "EDR"
+    - vendor: "Crowdstrike"
+    - name: "Falcon"
+    - version: Agent version
+    - agent_time: Agent local timestamp
+  - org: Organization information
+    - uid: Customer ID (CID)
+    - name: Service provider
+  - domain: Machine domain
+  - ou: Organizational unit
+  - first_seen_time: First seen timestamp
+  - last_seen_time: Last seen timestamp
+  - modified_time: Last modification timestamp
+  - is_compliant: Compliance status (boolean)
+  - groups: Array of groups
+    - name: Group name
+    - uid: Group ID
+  - location: Geographic location
+    - city: City name
+    - country: Country name
+    - continent: Continent name
+```
+
+### Enrichment Objects
+
+The connector includes enrichment objects with additional CrowdStrike-specific data:
+
+**Compliance Enrichment:**
+- **name**: "compliance"
+- **value**: "hygiene"
+- **data**:
+  - **Firewall_status**: Status of the device's firewall policy ("Enabled" or "Disabled")
+
+### Data Processing Notes
+
+1. **Timestamp Handling**: All timestamps from CrowdStrike are parsed from ISO 8601 format and converted to UNIX timestamps.
+
+2. **MAC Address Normalization**: MAC addresses are normalized to the standard format (e.g., "00:1A:2B:3C:4D:5E").
+
+3. **Device Type Mapping**: CrowdStrike's `product_type_desc` field is mapped to OCSF device types:
+   - Server → DeviceTypeId.SERVER
+   - Workstation/Desktop → DeviceTypeId.DESKTOP
+   - Laptop → DeviceTypeId.LAPTOP
+   - Mobile/Phone → DeviceTypeId.MOBILE
+   - Tablet → DeviceTypeId.TABLET
+
+4. **OS Type Mapping**: Platform names are mapped to OCSF OS types:
+   - Windows → OS_TYPE_WINDOWS
+   - Mac → OS_TYPE_MACOS
+   - Linux → OS_TYPE_LINUX
+   - iOS → OS_TYPE_IOS
+   - Android → OS_TYPE_ANDROID
+
+5. **Compliance Status**: Device compliance is determined based on multiple factors:
+   - Status is "normal"
+   - Not in reduced functionality mode
+   - Not in filesystem containment
+
+6. **Network Interfaces**: The connector creates multiple network interface entries when available:
+   - Primary interface (using local_ip and mac_address)
+   - Connection interface (using connection_ip and connection_mac_address if different from local)
+
+7. **Groups**: Device groups are extracted from the `groups` array, with the first two groups being prioritized.