Houdin.io

Houdin ships as a response integration in the Google SecOps Content Hub.

The Enrich Entities playbook step scans the entities of an alert with Houdin and adds the verdict to each of them. A widget shows the MesmerAI card on the alert.

Enrich Entities Playbook step

The step scans every IP, domain, URL and file hash of the alert on Houdin, then writes the verdict back on each one. The step runs again at the polling interval you set (30 seconds above) until every scan is done.

Parameter	Default	What it does
Scanners	empty	Comma-separated scanner shortnames. Empty runs the default set of your plan for each entity type. The verdict is always included.
Force Rescan	off	Skip the scan cache and query every source again.
Suspicious Threshold	7	An entity whose threat score reaches this value is marked suspicious. `off` disables marking.
Create Insight	on	Add an insight on each enriched entity with the verdict, the summary and a link to the scan.

Enrichment fields

Every field is prefixed with Houdin-io_; a field whose value would be empty is not written.

Field	Content
`Threat_Score`	The MesmerAI score, 0 to 10.
`Confidence`	`low`, `medium` or `high`.
`Confidence_Reason`	Why, in one sentence.
`AI_Analysis`	The verdict's written summary.
`Tags`	The verdict's tags, comma separated.
`Related_IOCs`	Up to five indicators worth pivoting to.
`Sources`	The scanners that ran, by shortname.
`Scan_ID`, `Scan_Link`, `Scan_Time`	Where to open the scan in Houdin, and when it ran.
`Unrecorded`	`true` when no source holds any record of the indicator. Treat the score as unknown rather than benign.

The step's JSON result is a list of { Entity, EntityResult }, where EntityResult is the full scan document. The widget reads it. The output message carries one line per entity with its score, confidence and link, and names the entities Houdin refused. A refusal that concerns the account rather than one entity fails the step with Houdin's own message: a rejected key, a spent monthly allowance, a daily cap, a scanner above the plan.

Scan Artifact Playbook step

The step scans one indicator you give it, for playbooks that build the artifact themselves, and returns the whole scan. It is asynchronous like Enrich Entities, so set its polling interval the same way.

Parameter	Default	What it does
Artifact		The indicator to scan: an IPv4, IPv6, domain, URL, MD5, SHA1, SHA256 or SHA512. Defanged forms such as `hxxp://` and `[.]` are accepted.
Scanners	empty	Comma-separated scanner shortnames. Empty runs the default set of your plan for that artifact type.
Force Rescan	off	Skip the scan cache and query every source again.

The JSON result is the scan document, the result value is true, and the step adds an Open in Houdin link to the case.

Ping Playbook step

Checks the API key of the instance and answers Successfully connected to the Houdin-io server with the provided connection parameters! The Test button of the instance dialog runs it.

Inside the package

core/houdin.py: HoudinManager, the API client. Launches scans, reads results, maps Houdin errors to step messages.
core/base_action.py: the base class of the three steps. Builds the client from the instance parameters and keeps the step's state between runs.
core/exceptions.py, core/data_models.py: the two error types (artifact refused, account refused) and the launch response.
core/houdin_constants.py: API root, step names, the Houdin-io_ prefix, scanner list, timeouts, default threshold.
core/houdin_utils.py: which entities are scannable, scan document to enrichment fields, insight and verdict line, parsing of the Scanners and Suspicious Threshold parameters.

Every scan launched from SecOps counts against the monthly allowance of the account that owns the key and lands in that account's history. The integration's source and release notes are in the Content Hub repository. Questions go to support@houdin.io.