feat(easm): add EASM source integration

docs/external-sources/easm/how-to/010_easm-source.md

@@ -0,0 +1,96 @@
+# External Attack Surface Management (EASM) Integration
+
+The EASM Integration of `ibdm` connects to the EASM backend via its REST API and reads a
+customer's latest completed scan run. It supports pull-based sync only.
+
+## Commands
+
+### Sync
+
+```sh
+ibdm sync easm --mapping-file <path to mapping file or folder>
+```
+
+Performs a one-off synchronisation: fetches the customer's latest completed run from the EASM
+`/data` endpoint as a single cursor-paginated list, emits one item per record routed by the
+record's own `type` field, and exits.
+
+## Configuration
+
+All configuration is read from environment variables.
+
+### Environment Variables
+
+| Env Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `EASM_BASE_URL` | Yes | _(empty)_ | Base URL of the EASM backend (e.g. `https://easm.example.com`). |
+| `EASM_CUSTOMER` | Yes | _(empty)_ | Customer identifier. Scopes the request to a single customer via the `X-Customer` header — it selects whose scan results to read. |
+| `EASM_TOKEN` | No | _(empty)_ | Bearer token authenticating the caller. When set, it is sent as `Authorization: Bearer <token>`. |
+| `EASM_DATA_PATH` | No | `/data` | Path of the read endpoint appended to `EASM_BASE_URL`. |
+| `EASM_HTTP_TIMEOUT` | No | `30s` | Timeout for each HTTP request, parsed as a Go `time.Duration`. |
+
+## Supported Data Types
+
+| Type | Sync |
+| --- | --- |
+| `domain` | ✅ |
+| `endpoint` | ✅ |
+| `host` | ✅ |
+| `ip` | ✅ |
+| `vulnerability` | ✅ |
+
+The endpoint tags each record with one of these types; records with a missing or empty `type`
+are skipped. Each emitted item carries the record's fields unchanged, and the pipeline can restrict
+a run to a subset of types via the mapping files — only the requested types are emitted.
+
+### `domain`
+
+One entry per discovered domain, including its DNS, WHOIS, zone-transfer, Azure, and
+misconfiguration data.
+
+### `endpoint`
+
+One entry per discovered endpoint.
+
+### `host`
+
+One entry per discovered host.
+
+### `ip`
+
+One entry per discovered IP address.
+
+### `vulnerability`
+
+One entry per discovered vulnerability.
+
+## Authentication
+
+The source scopes every request to a single customer with the `X-Customer` header, taken from
+`EASM_CUSTOMER` — this is always sent.
+
+When `EASM_TOKEN` is set, the source authenticates the caller with an
+`Authorization: Bearer <token>` header.
+
+## Example Mapping Files
+
+Example mapping files are provided in the `docs/external-sources/easm/mappings/` directory:
+
+- `domains.yaml` — maps domain records to Catalog items.
+- `endpoints.yaml` — maps endpoint records to Catalog items.
+- `hosts.yaml` — maps host records to Catalog items.
+- `ips.yaml` — maps IP records to Catalog items.
+- `vulnerabilities.yaml` — maps vulnerability records to Catalog items.
+
+These files can be used as a starting point for your own mapping configuration. Pass the file
+or the folder to the `--mapping-file` flag:
+
+```sh
+ibdm sync easm --mapping-file docs/external-sources/easm/mappings/
+```
+
+For local development and debugging, add the `--local-output` flag to send results to stdout:
+
+```sh
+ibdm sync easm --mapping-file docs/external-sources/easm/mappings/ --local-output
+```

docs/external-sources/easm/itds/domains.easm.unguess.io.yaml

@@ -0,0 +1,102 @@
+# yaml-language-server: $schema=https://cdn.mia-platform.eu/catalog/v1alpha1/mia-platform.eu.v1alpha1.ItemTypeDefinition.json
+---
+apiVersion: easm.unguess.io/v1
+kind: ItemTypeDefinition
+metadata:
+  name: domains.easm.unguess.io
+spec:
+  group: easm.unguess.io
+  names:
+    kind: Domain
+    plural: domains
+    singular: domain
+    displayPlural: Domains
+    displaySingular: Domain
+  scope: Organization
+  versions:
+    - deprecated: false
+      name: v1
+      schema:
+        openAPIV31Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                domain:
+                  description: The registered domain name.
+                  type: string
+                  title: Domain
+                dns:
+                  description: DNS records found for the domain.
+                  type: object
+                  title: DNS
+                  properties:
+                    dmarc:
+                      type: string
+                      title: DMARC
+                    spf:
+                      type: string
+                      title: SPF
+                    mx:
+                      type: array
+                      title: MX
+                      items:
+                        type: string
+                    ns:
+                      type: array
+                      title: NS
+                      items:
+                        type: string
+                whois:
+                  description: The raw WHOIS record for the domain (irregular structure, stored as-is).
+                  type: object
+                  title: WHOIS
+                  additionalProperties: true
+                zonetransfer:
+                  description: AXFR zone-transfer lines ("name\ttype\trdata"); absent when blocked.
+                  type: array
+                  title: Zone Transfer
+                  items:
+                    type: string
+                azure:
+                  description: Azure tenant attribution for the domain (absent when skipped or nothing found).
+                  type: object
+                  title: Azure
+                  properties:
+                    tenant_id:
+                      type: string
+                      title: Tenant ID
+                    namespace_type:
+                      type: string
+                      title: Namespace Type
+                    brand:
+                      type: string
+                      title: Brand
+                    federation_url:
+                      type: string
+                      title: Federation URL
+                    m365:
+                      type: boolean
+                      title: Microsoft 365
+                    admin_consent_exposed:
+                      type: boolean
+                      title: Admin Consent Exposed
+                misconfig:
+                  description: Cloud service misconfigurations discovered for the domain.
+                  type: array
+                  title: Misconfigurations
+                  items:
+                    type: object
+                    properties:
+                      service:
+                        type: string
+                        title: Service
+                      url:
+                        type: string
+                        title: URL
+                      status:
+                        type: integer
+                        title: Status
+      served: true
+      storage: true

docs/external-sources/easm/itds/endpoints.easm.unguess.io.yaml

@@ -0,0 +1,67 @@
+# yaml-language-server: $schema=https://cdn.mia-platform.eu/catalog/v1alpha1/mia-platform.eu.v1alpha1.ItemTypeDefinition.json
+---
+apiVersion: easm.unguess.io/v1
+kind: ItemTypeDefinition
+metadata:
+  name: endpoints.easm.unguess.io
+spec:
+  group: easm.unguess.io
+  names:
+    kind: Endpoint
+    plural: endpoints
+    singular: endpoint
+    displayPlural: Endpoints
+    displaySingular: Endpoint
+  scope: Organization
+  versions:
+    - deprecated: false
+      name: v1
+      schema:
+        openAPIV31Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                host:
+                  description: The host the endpoint belongs to.
+                  type: string
+                  title: Host
+                port:
+                  description: The port the endpoint listens on.
+                  type: integer
+                  title: Port
+                http:
+                  description: HTTP response details for the endpoint (absent when no HTTP answer).
+                  type: object
+                  title: HTTP
+                  properties:
+                    url:
+                      type: string
+                      title: URL
+                    scheme:
+                      type: string
+                      title: Scheme
+                    status_codes:
+                      type: array
+                      title: Status Codes
+                      items:
+                        type: integer
+                    content_length:
+                      type: integer
+                      title: Content Length
+                    title:
+                      type: string
+                      title: Title
+                    technologies:
+                      type: array
+                      title: Technologies
+                      items:
+                        type: string
+                tls:
+                  description: TLS report for the endpoint (success shape or an error; stored as-is).
+                  type: object
+                  title: TLS
+                  additionalProperties: true
+      served: true
+      storage: true

docs/external-sources/easm/itds/hosts.easm.unguess.io.yaml

@@ -0,0 +1,53 @@
+# yaml-language-server: $schema=https://cdn.mia-platform.eu/catalog/v1alpha1/mia-platform.eu.v1alpha1.ItemTypeDefinition.json
+---
+apiVersion: easm.unguess.io/v1
+kind: ItemTypeDefinition
+metadata:
+  name: hosts.easm.unguess.io
+spec:
+  group: easm.unguess.io
+  names:
+    kind: Host
+    plural: hosts
+    singular: host
+    displayPlural: Hosts
+    displaySingular: Host
+  scope: Organization
+  versions:
+    - deprecated: false
+      name: v1
+      schema:
+        openAPIV31Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                fqdn:
+                  description: The fully qualified domain name of the host.
+                  type: string
+                  title: FQDN
+                status_code:
+                  description: The DNS response status observed for the host.
+                  type: string
+                  title: Status Code
+                a:
+                  description: The IPv4 (A) records the host resolves to.
+                  type: array
+                  title: A Records
+                  items:
+                    type: string
+                aaaa:
+                  description: The IPv6 (AAAA) records the host resolves to.
+                  type: array
+                  title: AAAA Records
+                  items:
+                    type: string
+                cname:
+                  description: The CNAME records for the host.
+                  type: array
+                  title: CNAME Records
+                  items:
+                    type: string
+      served: true
+      storage: true

docs/external-sources/easm/itds/ips.easm.unguess.io.yaml

@@ -0,0 +1,61 @@
+# yaml-language-server: $schema=https://cdn.mia-platform.eu/catalog/v1alpha1/mia-platform.eu.v1alpha1.ItemTypeDefinition.json
+---
+apiVersion: easm.unguess.io/v1
+kind: ItemTypeDefinition
+metadata:
+  name: ips.easm.unguess.io
+spec:
+  group: easm.unguess.io
+  names:
+    kind: Ip
+    plural: ips
+    singular: ip
+    displayPlural: IPs
+    displaySingular: IP
+  scope: Organization
+  versions:
+    - deprecated: false
+      name: v1
+      schema:
+        openAPIV31Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                ip:
+                  description: The IP address.
+                  type: string
+                  title: IP
+                ptr:
+                  description: The PTR (reverse DNS) record for the IP.
+                  type: string
+                  title: PTR
+                ports:
+                  description: The open ports discovered on the IP.
+                  type: array
+                  title: Ports
+                  items:
+                    type: integer
+                geo:
+                  description: Geographic and network attribution for the IP.
+                  type: object
+                  title: Geo
+                  properties:
+                    provider:
+                      type: string
+                      title: Provider
+                    org:
+                      type: string
+                      title: Organization
+                    asn:
+                      type: string
+                      title: ASN
+                    region:
+                      type: string
+                      title: Region
+                    country:
+                      type: string
+                      title: Country
+      served: true
+      storage: true