SecurityScorecard

Overview

The SecurityScorecard integration connects Praetorian Guard Platform (PGP) to the SecurityScorecard API to import third-party security ratings data. It is a read-only integration — PGP pulls data from SecurityScorecard but never modifies your SecurityScorecard account.

Once connected, PGP automatically discovers every company domain across all your SecurityScorecard portfolios and imports their overall scores, letter grades, individual risk factor scores, six months of score history, and active security issues (mapped as Risks with severity levels).

What the Integration Does

When the integration runs, it performs the following steps:

  1. Validates your API key by calling the SecurityScorecard portfolios endpoint.

  2. Lists all portfolios in your SecurityScorecard account.

  3. Paginates through companies in each portfolio (50 companies per page, up to 200 pages per portfolio).

  4. For each unique company domain:

    • Creates a domain Asset in PGP.

    • Emits score and grade Attributes on the Asset.

    • Fetches the company's risk factor scores and emits each as an Attribute.

    • Fetches active security issues and creates Risks with mapped severity.

    • Fetches six months of monthly score history and emits score_history Attributes.

Companies are processed concurrently (up to 10 in parallel) for performance.

Severity Mapping

SecurityScorecard issue severities are mapped to PGP risk status codes as follows:

SecurityScorecard Severity

PGP Severity

high

Critical

medium

Medium

low

Low

info

Informational

positive

Not imported — positive findings are healthy practices, not risks

unknown/other

Informational (fallback)

Risk Factors

SecurityScorecard evaluates companies across ten risk factor categories. The integration imports each factor's numeric score (0-100) as an Attribute on the domain Asset. The ten standard SecurityScorecard risk factors are:

  1. Network Security — open ports, SSL configurations, insecure protocols

  2. DNS Health — DNS configuration issues, DNSSEC, MX records

  3. Patching Cadence — speed of applying security patches

  4. Endpoint Security — endpoint protection and configuration

  5. IP Reputation — malicious activity associated with IP ranges

  6. Application Security — web application vulnerabilities and headers

  7. Cubit Score — proprietary threat intelligence signal

  8. Hacker Chatter — dark web and underground forum mentions

  9. Information Leak — exposed credentials and sensitive data

  10. Social Engineering — phishing and social engineering susceptibility

Note: The factor names are returned dynamically by the SecurityScorecard API (e.g., network_security, dns_health). PGP stores whatever factor names the API returns as Attribute keys on each domain Asset.

Prerequisites

  • An active SecurityScorecard account with API access.

  • A SecurityScorecard API key (token-based authentication).

  • At least one portfolio with companies in your SecurityScorecard account.

How to Get Your API Key

  1. Log in to your SecurityScorecard account.

  2. Navigate to My Settings (gear icon in the top-right).

  3. Select API from the left sidebar.

  4. Click Generate New API Token (or copy your existing token).

  5. Copy the token — you will paste it into PGP during setup.

For full API documentation, see the SecurityScorecard API Reference.

Setup

  1. In PGP, navigate to Integrations from the left sidebar.

  2. Locate the SecurityScorecard card.

  3. Click the card to open the configuration form.

  4. Enter your API Key in the provided field.

  5. Click Connect to save and activate the integration.

Field Reference

Field

Required

Description

Username

Auto-filled

Automatically set to securityscorecard (hidden field). You do not need to enter this.

API Key

Yes

Your SecurityScorecard API token. Displayed as a password field for security.

Data Mapping

The integration maps SecurityScorecard data into PGP entities as follows:

Assets

SecurityScorecard Data

PGP Entity

Details

Company domain

Asset (domain)

Each unique company domain becomes an Asset. Both the Asset name and value are set to the domain (e.g., example.com).

Attributes

Attribute Name

Value

Source

score

Numeric score (0-100)

Company's overall SecurityScorecard score

grade

Letter grade (e.g., A, B, C, D, F)

Company's overall SecurityScorecard grade

{factor_name}

Numeric score (0-100)

Individual risk factor scores (e.g., network_security, dns_health). One Attribute per factor.

score_history

Format: YYYY-MM-DD:score

Monthly score data points for the last 6 months. One Attribute per month.

Risks

SecurityScorecard Data

PGP Entity

Details

Active issue

Risk

Each active issue becomes a Risk linked to the domain Asset. The Risk name is the issue type (e.g., csp_no_policy, open_resolver), and the severity is mapped per the table above.

API Endpoints Used

All API calls are made to https://api.securityscorecard.io using the header Authorization: Token {api_key} (note: Token format, not Bearer).

Method

Endpoint

Purpose

GET

/portfolios

List all portfolios (also used for credential validation)

GET

/portfolios/{id}/companies?page={n}&size=50

Paginate companies within a portfolio

GET

/companies/{domain}/factors

Fetch risk factor scores for a company

GET

/companies/{domain}/active-issues

Fetch active security issues

GET

/companies/{domain}/history/score?from={date}&to={date}&timing=monthly

Fetch monthly score history (last 6 months)

GET

/companies/{domain}

Check if a domain is tracked in SecurityScorecard (affiliation check)

Troubleshooting

Authentication Failed (HTTP 401)

If you see a credential validation error, verify that:

  • Your API key has not expired or been revoked in SecurityScorecard.

  • You copied the full API key without leading or trailing spaces.

  • Your SecurityScorecard account has API access enabled.

No Data Imported

  • Ensure your SecurityScorecard account has at least one portfolio containing companies.

  • Check your PGP asset filters — domains may be filtered out by your VM filter configuration.

Missing Active Issues for Some Companies

The SecurityScorecard /active-issues endpoint may return HTTP 500 errors for certain companies. PGP treats this as a non-fatal warning and continues processing. The company's Asset, score, grade, and risk factors will still be imported — only the active issues will be missing for that company.

Large Portfolios / Pagination Limits

Each portfolio is paginated at 50 companies per page with a safety limit of 200 pages (10,000 companies per portfolio). If you have more than 10,000 companies in a single portfolio, a warning is logged and remaining companies are skipped. Consider splitting very large portfolios.

Integration Timeout

The integration has a timeout of 120 seconds. If you have a very large number of portfolios and companies, the integration may time out. Contact support if this occurs consistently.

Duplicate Domain Handling

If the same domain appears in multiple portfolios, PGP processes it only once. The deduplication is automatic.