# Nucleus & OCSF Mappings

This document provides a detailed mapping of fields between Nucleus data and the OCSF schema. It includes mappings for both assets and findings, with sections for searching (Nucleus to OCSF) and creating/updating (OCSF to Nucleus).

## 1. Assets

### 1.1 Search Assets

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/assets/asset.json`
- **Purpose:** Maps asset-related data from Nucleus to OCSF for asset discovery and inventory.


| Nucleus | OCSF |
|  --- | --- |
| `asset_id` | `device.instance_uid` |
| `asset_name` | `device.hostname` |
| `ip_address` | `device.ip` |
| `mac_address` | `device.mac` |
| `operating_system_name` | `device.os.name` |
| `operating_system_version` | `device.os.version` |
| `scan_date` | `device.last_seen_time` |


### 1.2 Create Asset

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/assets/asset_create.json`
- **Purpose:** Maps asset data from OCSF to Nucleus for creating new asset records.


| OCSF | Nucleus |
|  --- | --- |
| `device.hostname` | `asset_name` |
| `device.ip` | `ip_address` |
| `device.mac` | `mac_address` |
| `device.os.name` | `operating_system_name` |
| `device.os.version` | `operating_system_version` |
| `device.network_interfaces.hostname` | `asset_name_secondary` |
| `device.network_interfaces.ip` | `ip_address_secondary` |


### 1.3 Update Asset

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/assets/asset_update.json`
- **Purpose:** Maps updated asset data from OCSF to Nucleus for updating existing asset records.


| OCSF | Nucleus |
|  --- | --- |
| `device.network_interfaces.hostname` | `asset_name_secondary` |
| `device.network_interfaces.ip` | `ip_address_secondary` |
| `device.mac` | `mac_address` |
| `device.os.name` | `operating_system_name` |
| `device.os.version` | `operating_system_version` |


## 2. Findings

### 2.1 Search Findings

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/findings/finding.json`
- **Purpose:** Maps finding-related data from Nucleus to OCSF for security analysis.


| Nucleus | OCSF |
|  --- | --- |
| `finding_number` | `finding.uid` |
| `finding_name` | `finding.title` |
| `finding_description` | `finding.desc` |
| `scan_date` | `time` |
| `scan_date` | `finding.scan_date` |
| `finding_discovered` | `finding.first_seen_time` |
| `scan_date` | `finding.last_seen_time` |
| `finding_recommendation` | `finding.remediation.desc` |
| `finding_severity` | `severity` |
| `finding_severity` | `severity_id` |
| `finding_state` | `state` |
| `finding_state` | `state_id` |
| `finding_status` | `activity_id` |
| `finding_status` | `activity_name` |
| `finding_status` | `type_uid` |
| `finding_status` | `type_name` |
| `finding_cve` | `vulnerabilities[].cve.uid` |
| `finding_references` | `vulnerabilities[].references` |
| `asset_id` | `resources[].uid` |
| `asset_name` | `resources[].name` |
| `ip_address` | `resources[].data.ip` |
| `finding_port` | `resources[].data.port` |
| `finding_path` | `resources[].data.path` |


### 2.2 Create Finding

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/findings/finding_create.json`
- **Purpose:** Maps finding data from OCSF to Nucleus for creating new finding records.


| OCSF | Nucleus |
|  --- | --- |
| `resources.index(0).uid` | `host_id` |
| `finding.title` | `custom_finding_name` |
| `finding.desc` | `custom_finding_description` |
| `finding.remediation.desc` | `custom_finding_recommendation` |
| `finding.first_seen_time` | `finding_discovered` |


### 2.3 Update Finding

- **Example JSON Path:** `services/engine/service/providers/nucleus/sampleEvents/findings/finding_update.json`
- **Purpose:** Maps updated finding data from OCSF to Nucleus for updating existing finding records.


| OCSF | Nucleus |
|  --- | --- |
| `finding.severity` | `finding_severity` |
| `finding.state` | `finding_status` |
| `unmapped.due_date` | `due_date` |
| `unmapped.comment` | `comment` |