Set up lywand software

Set up lywand software

lywand software is a third-party vulnerability scanning platform. When you connect lywand software to octoja, every device paired with lywand shows a security rank (A–F) and a list of open vulnerabilities directly on the device detail page. You can prioritise remediation work without leaving octoja, then click through to the lywand portal for the full vulnerability detail.

Prerequisites

• You need the Integration Management permission in octoja. Administrators assign permissions to groups under Administration → Groups.
• You need an active lywand software account with an API key. Generate it in your lywand portal — see lywand's own documentation for the exact location.
• Your lywand partner mapping has to overlap with the customers you have in octoja. Each octoja customer is matched to one lywand partner during setup.

Connect lywand software

1. Go to Administration → Integrations. The page is split into an Alerting section (Email, Microsoft Teams, Mobile push, Webhooks), a Ticketing systems section, and an Other platforms section. A search box at the top of the page filters the cards by name.
2. Under Other platforms, find the lywand software card and click Set up. You can also type "lywand" into the search box to jump straight to it.
3. Paste your lywand software API key into the setup dialog. octoja stores the key in your instance configuration and never returns it through the API — once saved you can no longer view it; rotate the key in lywand if you lose track of it.
4. Optionally, click the Test API key icon inside the input to pre-validate the key. A green "API key verified." line appears for a working key; a rejected key gets a red "lywand software rejected this API key." line with lywand's own reason underneath. You can skip this step — Save validates the key server-side too.
5. Click Save. The card switches to its connected layout: a customer-matched progress bar appears under the description, and the Match customers button plus the Disconnect icon (a small unplug symbol) appear in the card footer.

Match customers to lywand partners

octoja customers and lywand partners are independent entities — the customer named "Acme GmbH" in octoja is not automatically the same record as "Acme" in lywand. After connecting you must tell octoja which is which.

1. On the lywand software card, click Match customers.
2. The dialog lists each octoja customer in a row. Pick the matching lywand software partner from the picker on each row. Leave a row empty if the customer is not in lywand (its devices will show no score). Each partner can be used once — octoja rejects a save that points two customers at the same partner.
3. Click Save. octoja preserves these matches across disconnect and reconnect — you do not have to redo the mapping when rotating the API key.

The progress bar on the integration card turns green when all the customers you can access are matched, amber while the mapping is partial, and red while none of them is matched. Both numbers are scoped to your own customer access, so a colleague with a narrower scope can see a different bar on the same integration.

When you save, every matched customer automatically gets the customer tag lywand. Use it, for example, to target these customers through Customer Tags in a config package's targeting rules, see Assign checks with config packages. Removing a match does not remove the tag from the customer; remove it on the customer itself if needed.

Once everything is set up, the lywand software card in the Other platforms section looks like this:

Changing the mapping later

You can change the mapping at any time — expect a short gap in the display afterwards. When you remove a customer's match, octoja clears the scores of that customer's devices right away. When you assign a customer to a (different) lywand partner, the data for the new pairing arrives with the next background sync, which runs once an hour — so an empty lywand display right after saving is normal, and scores should be back within about an hour. If they are still missing a couple of hours after the change, check that the card shows no API-key alert and re-open Match customers to confirm the pairing — if both look right, contact support.

Where the data appears

Once lywand software is connected and customers are matched, vulnerability data surfaces across octoja:

• Devices list (/devices) — devices with a lywand score show their rank letter in an optional Lywand column; switch it on from the table's column menu. In the card view the rank appears on the device card without any extra step.
• Device detail page (/devices/<device>) — a compact Lywand Score tile in the metrics row shows the rank letter and how many vulnerabilities the device has. A Vulnerabilities tab renders the full table with CVEs, severity, CVSS vector, EPSS score, and remediation steps; its header repeats the rank and the score out of 10, and tells you when lywand last scanned the device. An external-link icon labelled Open in Lywand opens that device's vulnerability details in the lywand portal.
• Dashboard — when at least one device has a lywand score, the dashboard's device table adds a per-device Lywand column showing each device's rank letter.
• Customers — when at least one customer has a lywand score, the customer table adds a colour-coded, sortable Lywand column showing each customer's aggregate A–F rank, so you can spot your highest-risk customers at a glance. An individual customer's dashboard carries the same rank as a Lywand Score card.
• Reports — the built-in Lywand Security template summarises the current vulnerability landscape, and its widgets (score, critical CVEs, CISA KEV matches, affected devices, and a vulnerability table) are available for your own templates.
• Monitoring — the Lywand Vulnerabilities check turns a device's findings into an alert. It runs on the server against the data octoja already synced, and you choose which findings it looks at and what counts as a warning or a critical result: a critical finding being present, the risk score reaching or exceeding a threshold, or new findings appearing since the previous run.

When does the score appear?

A device shows a score when all of the following are true:

• The device's customer is matched to the right lywand partner (see above).
• The device is tracked in lywand through the lywand agent installed on it. Devices that lywand only scans remotely over the network are not paired with octoja devices and show no score.
• The device is managed by octoja for the same customer. octoja pairs its device record with lywand's automatically, using the machine identifier the lywand agent stores on the device — there is no manual per-device mapping. The pairing works for Windows devices.

The score reflects the currently imported, non-ignored findings in the selected software scope. A paired device with no such findings shows rank A, even before a scan has completed. A therefore does not prove a successful scan or a vulnerability-free device. On the Vulnerabilities tab, check the scan time; hover over the time to see Last scanned on …. Never scanned means no scan timestamp is available. Confirm a completed scan in lywand and subsequent synchronization before assessing the result. A blank score cell does not prove security either; check pairing and synchronization.

As for timing: octoja fetches new data from lywand once an hour, so fresh scan results — and the first scores after connecting or matching — appear at the latest about an hour later. A newly installed lywand agent takes one step more: octoja first has to pick up the new identifier during its regular device-inventory refresh, so allow a few hours before treating a blank score as a problem.

Understanding the score

Each vulnerability carries a risk value between 0 and 10. octoja aggregates a device's open vulnerabilities into a single device-level score that scales 0 (best) to 10 (worst) — a higher score means a worse security posture. Findings you have ignored in lywand stay in the list but never move the score. The aggregation follows lywand's published scoring methodology; see lywand's own documentation for the formula. octoja maps the score to a six-letter rank:

Choose which findings the score covers

Not every finding is yours to fix, so octoja keeps three scores side by side for every device and every customer:

Hover any rank octoja shows you — the tile, a table cell, the customer card — and a small panel lists all three scores at once and lets you switch between them. octoja remembers your choice in that browser and applies it everywhere a lywand rank appears, so the devices list, the dashboard, the customer table and the device tile always agree with each other. The Lywand Vulnerabilities check and the report widgets carry their own scope setting instead, so switching your view never changes what a monitored alert or a scheduled report covers.

Severity labels on individual vulnerabilities (Critical, High, Medium, Low) come straight from lywand and are independent of the device's aggregate score. A device can hold an A rank overall while a single vulnerability is labelled Critical — either because its risk value is low enough to barely contribute to the aggregate, or because the finding is ignored, or because it sits outside the scope you are currently looking at.

What octoja shows per vulnerability

The vulnerability table on the device detail page exposes:

• Vulnerability name and a short Description from lywand
• Product — the affected software lywand identified
• Severity badge (Critical / High / Medium / Low)
• Risk score (0 – 10) with colour coding (yellow → orange → red, no green — see note below)
• CVE identifiers when lywand has mapped the finding to one or more CVEs
• CVSS base vector when available
• EPSS score (Exploit Prediction Scoring System) when lywand provides it — useful for prioritising findings the wider security community is actively exploiting
• CISA KEV flag — when set, the CVE is on the US Cybersecurity and Infrastructure Security Agency's Known Exploited Vulnerabilities catalogue
• Technical Solution — lywand's recommended remediation step
• Detected timestamp
• Managed marker — whether the finding sits inside the customer's lywand service package. The column shows in the general view, and the risk value of an excluded row is greyed out with a tooltip explaining why it does not count.

A General view / Managed / Unmanaged filter above the table narrows the list to one group and shows how many findings sit in each. It is the same control as the score scope described above, so switching it also switches the rank octoja displays.

Expanding a row reveals the full detail and up to two actions. Both need the Software Management device action on that device.

• Ignore, with an optional reason — octoja writes the ignore back to lywand, the row stays visible marked Ignored, and it stops counting towards the score until you un-ignore it. The expanded row of an ignored finding carries an Ignored in Lywand panel holding the reason you gave and a line naming who ignored it and when — and that is where the Un-ignore button sits.
• Resolve — octoja looks the affected product up in the device's installed software, matches it to a Chocolatey or winget package, and offers to Update to latest or Uninstall it. The dialog names the match it found and how confident it is before you commit, and octoja re-scans the device afterwards so the finding clears. Resolve appears on Windows devices, for findings that are not ignored and name a product.

The risk score has no "green" tier in the UI: no vulnerability is "good". The lowest-risk visible colour is amber, not green, to keep low-risk findings from looking dismissable. The aggregate rank (A–F) does use green for A and B — there the green is meaningful because zero or near-zero vulnerabilities is a real outcome.

Update affected devices together

In Resolve, the affected-device table lists up to 100 matching devices within your access scope and shows their connection, policy coverage and update outcome. Select the devices and choose Update selected. You need Software Management on each target. Only online devices are contacted; offline devices are recorded as skipped, not queued for later. Review succeeded, failed and skipped outcomes separately.

With Monitoring Check Management, Add to configuration package adds the matched package as Update only, version latest, in system context. Select a rule-based package and choose Add update. Its existing targeting rules decide which devices receive the update; the selected rows in the immediate-update table do not change those rules. Policy coverage means a matching deployment is assigned, not that it has succeeded or fixed the finding. Confirm deployment and a subsequent lywand scan before treating the vulnerability as resolved.

Rotate the key or disconnect

• Rotate proactively while the key is still valid: a connected card shows only Match customers and Disconnect — there is no Update key button until the stored key stops working. To swap in a new key, click Disconnect, confirm, then Set up again with the new key. Your customer matches are preserved across the disconnect, so you do not have to redo them.
• Lywand has rejected your key: the card shows an inline alert ("The API key is no longer valid. Update it to keep receiving data from lywand software.") inside the card body, and an Update key button appears. Click it, paste the new key, and Save — no disconnect needed in this case.
• Disconnect for good: click Disconnect and confirm. The next sync stops, and the rank cells disappear from devices on the next page refresh.

Tips

• To roll the Lywand agent out to your Windows devices, use the prebuilt automation action Ensure Lywand agent — see Ensure Lywand agent. It resolves each device's license from the customer match automatically.
• The background sync runs once an hour and is not user-triggered. Newly discovered vulnerabilities show up at the next sync.
• If a device has no lywand score (blank cell), check the customer mapping, lywand inventory, pairing through the machine identifier and synchronization. See When does the score appear?.
• Open in Lywand on the device's Vulnerabilities tab opens that device's vulnerability details in the lywand portal — handy for jumping into the vendor's UI with the raw scan output already loaded.
• Troubleshooting: if scores stay blank after a connect, check that the API key was accepted (the card shows no "API key is no longer valid" inline alert); confirm the customer is mapped in Match customers; check Product Status & Known Limitations for any current lywand sync issues.