# Securityscorecard

SureCloud connects to SecurityScorecard to retrieve security scorecards, factor-level findings, and vendor portfolio monitoring data. This allows SureCloud to incorporate external cyber risk assessments into your compliance evidence — confirming that your organisation's scorecard is being tracked, that vendor security ratings are being monitored, and that changes in vendor posture are being captured for third-party risk management controls.

## Authentication and setup

SecurityScorecard authenticates API requests using an API key associated with your account.

{% stepper %}
{% step %}
**Generate an API key in SecurityScorecard**

Log in to SecurityScorecard at [securityscorecard.com](https://securityscorecard.com/). Navigate to **My Settings → API** and click **Generate API Token**. Name it `SureCloud CCM`. Copy the token.
{% endstep %}

{% step %}
**Enter the API key in SureCloud**

Navigate to **SureCloud → Integrations → SecurityScorecard → Connect**. Paste the API key and click **Save**.
{% endstep %}

{% step %}
**Test the connection**

Click **Test Connection**. SureCloud will call `GET /companies/score` to verify the key and confirm access to scorecard data.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API key securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **SecurityScorecard → My Settings → API** and update it in **SureCloud → Integrations → SecurityScorecard → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                | Use Case                                                           |
| --------------------------------------- | ------------------------------------------------------------------ |
| `GET /companies/{domain}/score`         | Retrieve the current security score for your organisation's domain |
| `GET /companies/{domain}/factors`       | Retrieve factor-level scores (Network Security, DNS Health, etc.)  |
| `GET /companies/{domain}/issues`        | Retrieve specific issues driving each factor score                 |
| `GET /portfolios`                       | List vendor portfolios configured for monitoring                   |
| `GET /portfolios/{id}/companies`        | Enumerate companies in a portfolio and their current scores        |
| `GET /companies/{domain}/history/score` | Retrieve historical score trend for longitudinal evidence          |

## Pagination

`GET /portfolios/{id}/companies` and `GET /companies/{domain}/issues` use page-based pagination. SureCloud increments the `page` parameter until the returned count falls below the page size.

```
GET /portfolios/{id}/companies?page=2&size=100
```

## Required permissions

SecurityScorecard API keys are account-scoped and provide read-only access to scorecard and portfolio data. No write or portfolio-management permissions are required.

## Polling frequency

| Data Type                   | Interval       |
| --------------------------- | -------------- |
| Organisation security score | Every 24 hours |
| Factor scores and issues    | Every 24 hours |
| Portfolio vendor scores     | Every 24 hours |
| Historical score data       | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API key is invalid or has been revoked. Navigate to **SecurityScorecard → My Settings → API**, regenerate the token, and update it in **SureCloud → Integrations → SecurityScorecard → Edit Connection**.

</details>

<details>

<summary>Portfolio companies return empty</summary>

Portfolios must be created and populated in SecurityScorecard before they appear via the API. Navigate to **SecurityScorecard → My Portfolios** and confirm vendor companies have been added. If no portfolios exist, the endpoint will return empty.

</details>

<details>

<summary>Score data appears outdated</summary>

SecurityScorecard updates scores on its own collection schedule (typically weekly for most factors). SureCloud reads the most recently available score at the time of polling. Score changes will reflect on the next SecurityScorecard refresh cycle, not in real time.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/securityscorecard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.