Sekoia

Sekoia

Website:  https://www.sekoia.com 
Documentation:  https://docs.sekoia.com 

1) Send your simulation events to Sekoia

The Sekoia connector does two things for you. Like every BlackNoise's connector, it provides, for each simulation event, an access URL that opens Sekoia directly on the information relevant to that event. In addition, it sends each simulation event to your Sekoia tenant as a log. Your simulation activity then sits next to your real telemetry: you can search it, correlate it with your detections, and confirm that what BlackNoise executed was actually visible to your SOC.
Sekoia never stores raw logs: everything that enters a tenant goes through an intake, and an intake is always bound to a format, the component that turns an incoming log into searchable fields. The BlackNoise format is currently being validated by Sekoia, so it does not appear yet in the Sekoia catalog. Until it does, you declare it yourself in your tenant with Add a custom format, from the parser published in this documentation. A custom format is private to your tenant, you can edit it at any time, and it requires no action from Sekoia support.

2) What each BlackNoise event carries

Every BlackNoise simulation event sent to Sekoia carries what your analysts need to identify the simulation and place it in your telemetry:
  • what was executed: the event name and description, its BlackNoise identifier, and its severity;
  • where: the System Target (name and IP address) or the cloud target, and the Attack Vector that ran it;
  • when: start and end times of the execution, so the event lines up with your own logs;
  • the attack it replicates: MITRE ATT&CK tactic and techniques, normalized into the standard Sekoia fields, so you can pivot from a simulation to your real detections on the same technique;
  • its outcome in BlackNoise: execution status, exploitation status, and the qualification recorded in BlackNoise (detection status, detection sources, time to detect and to respond);
  • the associated recommendations: Sigma and Suricata rules provided by BlackNoise, when the event has any.
BlackNoise-specific information is grouped under blacknoise.*, while the fields that have a standard equivalent (target address, technique, timestamps, outcome) are also normalized so they behave like the rest of your telemetry.
Simulation events are sent to your tenant, never read back from it. The intake key only allows writing, and BlackNoise makes no other use of your Sekoia data.

3) Setup the Sekoia connector in BlackNoise with the intake

Before you start

You need:
  • a BlackNoise account of a company allowed to use connectors. The connector configuration is per company: what you configure applies to every campaign of that company. If the Connectors entry is missing from the navigation, your account lacks the connector right, ask your BlackNoise administrator;
  • a Sekoia account allowed to manage intakes and formats, typically an Administrator or Integration manager role;
  • the Sekoia API URL of your tenant. The main region uses https://api.sekoia.io; a regional tenant uses https://app.<region>.sekoia.io/api (for example https://app.fra2.sekoia.io/api). This is the only URL BlackNoise asks you for, it derives the intake address and the Sekoia links from it;
  • the BlackNoise parser, a YAML document published in this documentation (see Step 2)
Get the BlackNoise parser
The parser is not distributed by the BlackNoise platform: it is not downloadable from the Connectors page and no field of the connector contains it. It is published here, in this documentation, alongside a sample simulation event.
Two ways to take it, both equivalent:
  • download the file attached to this page, recommended, it guarantees the document is complete;
  • copy the YAML block below it, with the copy button of the code block rather than a manual text selection, which tends to truncate the end of the document.
The parser is the same for every tenant: there is nothing to adapt in it, and no value of yours to fill in. The parser evolves with the information BlackNoise sends, and this page always carries the current version.

Step 1 - Configure the API URL in BlackNoise

Log in to BlackNoise, then in the Resources section of the navigation, open Connectors.
On the Sekoia card, click Configure. The Edit connector window opens, this is the window you will come back to in step 4.
Fill in the API URL with the Sekoia API address of your tenant, for example https://api.sekoia.io, or your regional address. Leave Intake Key empty for now: you do not have it yet, and it is optional.

Click Save and connect, and check that BlackNoise reports a success and not an error. The result of this first test tells you that the URL has the expected form, and it lists the addresses BlackNoise derived from it, the Sekoia web application used for the links, and the intake address the simulation events will be pushed to. Read them: this is where you see, before going any further, that BlackNoise is aimed at the right region.
The API URL is the Sekoia API address, not a page of the Sekoia web interface. The address of the intake page you will be on in step 3 (https://app.sekoia.io/intakes/…) is rejected by the test.

Step 2 - Declare the BlackNoise format in your tenant

This step is temporary: it is only needed while the BlackNoise format is being validated by Sekoia. Once the official format is published in the Sekoia catalog, skip straight to step 3 and pick BlackNoise from the catalog.
In the Sekoia web app, open Intakes in the Operations Center, then click Add a custom format.
Fill in the format identity:
Field
Value
Name
BlackNoise
Description
Breach & Attack Simulation events pushed by the BlackNoise platform.
Connector
None
DataSources
None
Save. Sekoia creates the format with an empty parser.
Edit the format you have just created: it opens directly on its "Parser" tab. The default viewof the editor does not let you paste, click "Expert mode", the code icon on the right of theeditor, then paste the YAML document taken from this page. Do not edit it: it is what makes thefields searchable, and any change to it changes what your detection rules and dashboards can see.

parser.yml
16KB, Uploaded 3 days ago

https://slite.com/api/files/KHrX-Ia1gx7j1v/image.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoia0RSejZ6ZnBRVEVRMVciLCJpYXQiOjE3ODkxNTUyNzEsImlzcyI6Imh0dHBzOi8vc2xpdGUuY29tIiwianRpIjoiZzJ6U2NIdjZNYnpId24iLCJleHAiOjE3OTE3NDcyNzF9.F6r3LifQgAF4Uljwne3VeTIpmZfiykPk4GhMdysQJ5Q
Before saving, use the test panel on the same screen. Paste the sample event published next to the parser on the left, and check that the right-hand side is populated, in particular a rule name, a timestamp and a set of blacknoise.* fields. An empty result means the document was not pasted completely: download the file rather than copying it again. Save the parser.
{"id": "8f14e45f-ceea-467a-9a1f-6b1a1e2c3d40", "campaign_id": "3c59dc04-8e88-4b53-9a4f-2b1c5d6e7f80", "campaign_name": "Quarterly assessment", "simulation_id": "b6d767d2-f8ed-4d51-9f2a-3c4b5a6d7e81", "execution_id": "c_37693cfc-748f-4a19-8b2e-9d0f1a2b3c40", "target_id": "1ff1de77-4005-4f2b-8c3d-5e6f7a8b9c02", "source": "192.0.2.50", "name": "Session Creation: Password Authentication", "event_bn_id": "BLCKNS_LAT_N0009.030", "description": "An attacker authenticates to a remote host using a valid password to move laterally.", "severity": "high", "tactic": "lateral_movement", "techniques": ["T1021.003", "T1021.004", "T1021.006"], "execution_status": "executed", "exploit_status": "exploited", "detection_status": "alerted", "execution_message": "Session opened on the remote host.", "ip_targets": ["192.0.2.10"], "start_time": "2026-01-20T18:53:00+00:00", "end_time": "2026-01-20T18:53:47+00:00", "detection_time": "2026-01-20T18:54:02+00:00", "reaction_time": "2026-01-20T18:58:30+00:00", "detection_sources": ["HarfangLab", "Sekoia"], "reaction_sources": ["HarfangLab"], "mtt": {"d": {"value": 1, "percent": 100}, "r": {"value": 4, "percent": 100}}, "system_target": {"id": "8e296a06-7b6e-4a3f-9c1d-2e3f4a5b6c03", "name": "dc01.test.local", "environment": "windows", "ip_address": "192.0.2.10"}, "recommendations": {"sigma_rule": "title: Remote Session Creation\\nstatus: stable", "suricata_rule": null}}

Step 3 - Create the intake and copy the intake key

Still in Intakes, click New intake. Search the catalog for BlackNoise and select it, the custom format you declared in step 2 appears there like any catalog format.
Give the intake a name that identifies it in your tenant, for example BlackNoise, BAS simulations, then attach it to the entity the simulation events belong to (and to a community, on a multi-community tenant). Save.
Sekoia then generates the intake key and displays it in the intake details window. Copy it now: this is the value BlackNoise needs, and copying it here saves you a detour through the intake page. Once the key is in your clipboard, close that window, the intake is created, you have nothing else to do on the Sekoia side.
The intake key is a credential, it authorizes writing logs into your tenant. Treat it like a password: store it in your password manager, and never paste it into a ticket or a chat.

Step 4 - Fill in the intake key in BlackNoise

Go back to BlackNoise, Resources → Connectors, and click Configure on the Sekoia connector again. In the Edit connector window, paste the key you have just copied into the Intake Key field, leaving the API URL as it is.

https://slite.com/api/files/kOKBrvb_w06hfy/image.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoia0RSejZ6ZnBRVEVRMVciLCJpYXQiOjE3ODkxNTUyNzEsImlzcyI6Imh0dHBzOi8vc2xpdGUuY29tIiwianRpIjoiZzJ6U2NIdjZNYnpId24iLCJleHAiOjE3OTE3NDcyNzF9.F6r3LifQgAF4Uljwne3VeTIpmZfiykPk4GhMdysQJ5Q

Click Save and connect. BlackNoise now reports two results instead of one:
Result
What it checks
API URL
That the address has the expected form. No request is sent. The message lists the addresses BlackNoise derived from it, so you can confirm them at a glance.
Intake connection
That the intake key is accepted, by sending one test log to your tenant. Skipped as long as no intake key is configured.
Sekoia offers no way to validate a key without ingesting anything, so that test log is a real log in your tenant. It is easily recognizable and can be excluded from your dashboards and alerting, see "Recognize a connection test" section.
The intake key stays optional. Without it, the connector remains operational and keeps providing the Sekoia access URLs on your simulation results; only the sending of events is skipped. You can add the key later without reconfiguring anything else.

Step 5 - Run a campaign with the Sekoia connector

The connector is configured; it now has to be selected on a campaign.
Create your campaign as usual, an Attack Vector to execute the simulation from, and the System Targets to run it against. See the campaign creation documentation for these steps, they are not specific to Sekoia.
In the connectors step of the campaign creation, select Sekoia among the connectors you have configured, then launch the simulation.
Only the campaigns on which the connector is selected send their events. A campaign created before the connector was configured does not send anything retroactively.

Step 6 - Check that your simulation events arrive

Events are sent as each simulation event finishes executing, so they appear in Sekoia during the campaign run, without waiting for the whole simulation to complete.
In Sekoia, open the intake you created: you should see one log per executed simulation event. The Events view gives you the same thing with the full search syntax, filter on event.dataset: blacknoise.simulation.
Filters worth keeping at hand:
To see
Filter
Everything sent by BlackNoise
event.dataset: blacknoise.simulation
Simulation events only
event.action: simulation_event
One campaign
blacknoise.campaign_id: "<campaign id>"
One simulation event
trace.id: "<execution id>"
One System Target
host.ip: "<target ip>"
A single MITRE ATT&CK technique
threat.technique.id: "<technique>"

Open the Sekoia log of one simulation event

You never have to type an execution identifier by hand. From BlackNoise:
    open the campaign, then its Kill chain tab;
    click the simulation event you are interested in;
    in the event panel, scroll down to the Connectors section;
    click View this event in Sekoia.
The link opens Sekoia already filtered on that execution identifier and on the execution window, so you land on the log of that exact run.

Recognize a connection test

Each time you click Save and connect on the connector, one test log is ingested. It is not a simulation and carries no campaign, simulation or target. Exclude it from your reporting with blacknoise.execution_id: "connector-healthcheck", or find it with rule.name: "BlackNoise connector healthcheck".

Troubleshooting

Symptom
Likely cause
Fix
The API URL result fails on its own
The address of a Sekoia web page was entered instead of the API address
Use https://api.sekoia.io or https://app.<region>.sekoia.io/api
The intake connection result fails with an authorization error
Wrong intake key, or a key belonging to another tenant
Copy the key again from the intake page in Sekoia
The intake connection result fails with a not-found error
Wrong region: the derived intake address does not exist
Check the API URL, in particular the /api path of regional tenants
No BlackNoise event after a campaign
No intake key on the connector, or the connector was not selected on the campaign
Fill in the intake key, re-test, and check the campaign configuration
Events appear but their fields are empty
The parser was not pasted completely, or was modified
Download the parser from this page, paste it again, and re-run the test panel
Sekoia reports events with no extracted field
The intake is bound to another format
Check that the intake uses the blacknoise-aev custom format

Good to know

  • A custom format is local to your tenant. If you use several tenants, repeat steps 2 and 3 in each of them.
  • The custom format does not update itself. When BlackNoise enriches the information it sends, an updated parser is published on this page: take it again and paste it over the previous one.
  • Detection rules and dashboards built on this custom format will have to be re-pointed once the official BlackNoise format is available in the Sekoia catalog.
  • Connection-test logs are ingested, stored and counted like any other log in your tenant.

References

  • Sekoia: Manage intakes:  https://docs.sekoia.com/xdr/features/collect/manage_intakes/ 
  • Sekoia: Create a custom format:  https://docs.sekoia.com/integration/develop_integration/formats/create_a_format/