Check a vulnerability in a campaign

A campaign can ask one question of every component: "are you hit by this vulnerability?". You give the number of the vulnerability (CVE-2021-23337, for example), and the campaign shows which components pass, which fail, and which Astrolabe could not tell.

Before you start

• You are an administrator.
• Compass, Campaigns and Tech stack are on in Administration › Plugins. The campaign reads what the Tech stack tab of each component found: see See a component's tech stack.
• The components you want to check have been analysed: their Tech stack tab shows their dependencies.

1. 📝 Write the check

1. In Administration, under INTELLIGENCE, click Compass, then the Assessments tab.

2. Click Create assessment.

3. Fill in the form:

   Field	What to write	Example
   Name	What the check says	Not hit by CVE-2021-23337
   Datasource	The source of the answer	Tech stack
   Datapoint	The value to read	Not affected by a vulnerability
   Passes when the check is	What it must be	True
   Vulnerability	The number of the vulnerability: a CVE, or a GitHub advisory such as GHSA-35jh-r3h4-6jhm	CVE-2021-23337

4. Click Save. The check is in the table of the Assessments tab.

2. 🚩 Create the campaign

1. In the side bar, click Campaigns, then Create campaign (or Create my first campaign).

2. Details: fill in Name (Patch lodash), Owner (platform-team), Description, Start Date and End Date, then click Next.

3. Checks: in Datasource, choose Tech stack. In Checks, choose Not hit by CVE-2021-23337. Click Next.

4. Filters: leave Entity Kind on Component to check every component, or narrow it with Entity Type and Owner (optional). Click Next.

5. Milestones, then Notifications: click Next on each.

6. Review: read the summary, then click Save.

3. 👀 Read the verdict

1. On the Campaigns page, click the campaign.

2. In the Components table, the column named after your check gives one mark per component:

   You see	It means
   passed	The component does not install an affected version.
   failed	The component installs an affected version.
   not measured	Astrolabe could not tell. This does not count for or against the component.

   Over the table, Completion Rate counts only the components Astrolabe could measure. A line above the progress bar says how many checks could not be measured.

4. 🧭 Get a note per component

A compass groups your checks and gives every component a note. Put the check in one.

1. In Administration, under INTELLIGENCE, click Compass. On the Compasses tab, click Create compass.

2. In Name, write Lodash watch. Under Assessments, click Add Assessment, tick Not hit by CVE-2021-23337, then click Save Selected Assessments.

3. Click Save. The compass has its card on the Compasses tab.

4. On the card, click the switch at the top right: a new compass is off.

5. Click Run calculations on the card. Calculations completed appears, and the card shows the number of components and the Average score.

6. Click View scores. The table has a column named after your compass: 100% for a component that passes, 0% for one that fails, Not measured for one Astrolabe could not tell.

5. 🔎 Read the answer on a component

1. In the side bar, click Catalog, then open a component, then its Compass tab.

2. Click the check Not hit by CVE-2021-23337 under Assessments. For a component that installs an affected version you read:

   • Result: Failed
   • Read: “lodash 4.17.20 (web/package.json)”: the dependency, its version and the file.
   • Fix it in the source, a link to the repository of the component.

   For a component that does not install one, Result: Passed and Read: “lodash 4.17.21 (web/package.json)”.

3. For a component Astrolabe never analysed, the check says Not measured: The tech stack has not read the default branch of this component yet: open its Tech stack tab, or wait for the nightly reading. Above, a banner adds Some checks could not be measured: they count neither for nor against the score.

✅ That's it!

❓ Questions

Does a component that is not measured count as safe? No. It counts neither for nor against: only a component that the Tech stack tab analysed can pass.

🛠️ Troubleshooting

What you see	What to do
No Compass tab on a component, no Campaigns entry in the side bar, or no Tech stack in Datasource	Turn on Campaigns, Compass and Tech stack in Administration › Plugins.
N check(s) could not be measured: they count neither for nor against. above the progress bar, or The tech stack has not read the default branch of this component yet: open its Tech stack tab, or wait for the nightly reading. in the Compass tab	Open the Tech stack tab of the components marked not measured. A component with no analysis there cannot be checked: fix what that tab says, then open the campaign again.

Next: Add the Compass card to your dashboard.