> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensourcemalware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check and enrich threats

> Use the two-step check-and-enrich workflow to identify malicious packages and retrieve full threat intelligence including IOCs.

This guide walks through the two-step workflow for checking whether an open-source package is malicious and retrieving detailed threat intelligence. It's useful for integrating into your SOAR or security tooling to automatically check resources and trigger downstream blocking or alerting when a match is found.

<Note>
  Subscription Required: This uses a paid endpoint available to Researcher Pro and Enterprise users.
</Note>

<Steps>
  <Step title="Check if a resource is malicious">
    Use the `check-malicious` endpoint to query OpenSourceMalware for a specific package.

    ```bash theme={null}
        curl -s "https://api.opensourcemalware.com/functions/v1/check-malicious?report_type=package&resource_identifier=latinum-wallet-mcp&ecosystem=pypi" \
          -H "Authorization: Bearer osm_your_token"
    ```

    ### Response — malicious package found

    ```json theme={null}
        {
          "malicious": true,
          "report_type": "package",
          "resource_identifier": "latinum-wallet-mcp",
          "ecosystem": "pypi",
          "version": null,
          "osm_url": "https://opensourcemalware.com/pypi/latinum-wallet-mcp",
          "last_scanned_at": "2026-03-31T22:15:00Z",
          "scan_result": true,
          "scan_severity": "critical",
          "last_osm_score": 82,
          "scan_count": 3,
          "threat_count": 1,
          "details": {
            "threat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "severity_level": "critical",
            "description": "Malicious PyPI package stealing Solana wallet credentials",
            "version_info": "all"
          }
        }
    ```

    ### Response — clean package

    ```json theme={null}
        {
          "malicious": false,
          "report_type": "package",
          "resource_identifier": "requests",
          "ecosystem": "pypi",
          "last_scanned_at": "2026-03-30T10:00:00Z",
          "scan_result": false,
          "scan_severity": null,
          "last_osm_score": 5,
          "scan_count": 12,
          "message": "Resource not found in malicious database"
        }
    ```
  </Step>

  <Step title="Interpret the response">
    Use this logic to decide your next step based on the response:

    ```text theme={null}
      if response.malicious == true:
        → Proceed to Step 3 using details.threat_id
        → Block or quarantine the package immediately

      if response.malicious == false AND response.last_scanned_at is recent:
        → Package is likely safe, no further action needed

      if response.malicious == false AND response.last_scanned_at is old (or null):
        → The package hasn't been evaluated recently
    ```

    <Tip>
      What counts as "recent" depends on your risk tolerance. For most teams, a scan within the last 7 days is sufficient. For high-security environments, you may want scans within 24 hours.
    </Tip>
  </Step>

  <Step title="Retrieve full threat intelligence">
    When `check-malicious` returns `malicious: true`, use the `threat_id` from the response to pull the full threat description and associated IOCs. This step requires a Pro or Enterprise API key.

    ```bash theme={null}
        curl -s "https://api.opensourcemalware.com/functions/v1/threat-data?threat_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
          -H "Authorization: Bearer osm_your_token"
    ```

    ```json theme={null}
        {
          "threat": {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "package_name": "latinum-wallet-mcp",
            "resource_identifier": "latinum-wallet-mcp",
            "report_type": "package",
            "registry": "pypi",
            "severity_level": "critical",
            "threat_description": "Malicious PyPI package masquerading as a Latinum AI MCP wallet integration. Imports a hidden solana_wallet_mcp module that exfiltrates Solana wallet private keys to attacker-controlled infrastructure at facilitator.latinum.ai.",
            "version_info": "all",
            "tags": ["cryptostealer", "mcp", "solana"],
            "osm_url": "https://opensourcemalware.com/pypi/latinum-wallet-mcp",
            "iocs": [
              {
                "ioc_type": "domain",
                "value": "facilitator.latinum.ai",
                "description": "C2 exfiltration endpoint"
              },
              {
                "ioc_type": "domain",
                "value": "latinum.ai",
                "description": "Attacker infrastructure"
              },
              {
                "ioc_type": "url",
                "value": "https://api.mainnet-beta.solana.com",
                "description": "Solana RPC endpoint used for wallet operations"
              },
              {
                "ioc_type": "file_hash_sha256",
                "value": "093d3e79a28b0b20937bb2094a9053ba1676dce1715e6434791d32d66a2ad78b",
                "description": "Payload file hash"
              },
              {
                "ioc_type": "email_address",
                "value": "dennj@latinum.ai",
                "description": "Publisher email"
              }
            ]
          }
        }
    ```
  </Step>
</Steps>

This workflow also works for other resource types:

### Repository

```text theme={null}
?report_type=repository&resource_identifier=https://github.com/org/repo
```

### Domain

```text theme={null}
?report_type=domain&resource_identifier=malicious-domain.com
```

### URL

```text theme={null}
?report_type=url&resource_identifier=https://evil.com/payload.js
```

### Container

```text theme={null}
?report_type=container&resource_identifier=malicious/image:latest
```

<Steps>
  <Step />
</Steps>

## Full example script

This JavaScript example puts both steps together into a single reusable function.

```javascript theme={null}
const API_KEY = 'osm_your_token';
const BASE = 'https://api.opensourcemalware.com/functions/v1';

async function checkAndEnrich(packageName, ecosystem) {
  // Step 1: Check if malicious
  const checkUrl = `${BASE}/check-malicious?report_type=package&resource_identifier=${packageName}&ecosystem=${ecosystem}`;
  const checkRes = await fetch(checkUrl, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  const checkData = await checkRes.json();

  console.log(`Package: ${packageName} (${ecosystem})`);
  console.log(`Malicious: ${checkData.malicious}`);
  console.log(`Last scanned: ${checkData.last_scanned_at || 'never'}`);
  console.log(`OSM Score: ${checkData.last_osm_score ?? 'n/a'}`);

  if (!checkData.malicious) {
    console.log('Not found in threat database');
    return;
  }

  // Step 2: Get full threat details + IOCs
  const threatId = checkData.details.threat_id;

  const detailRes = await fetch(`${BASE}/threat-data?threat_id=${threatId}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  const detailData = await detailRes.json();
  const threat = detailData.threat;

  console.log(`\nDescription: ${threat.threat_description}`);
  console.log(`Severity: ${threat.severity_level}`);
  console.log(`Tags: ${threat.tags?.join(', ')}`);
  console.log(`View: ${threat.osm_url}`);
  console.log(`\nIOCs (${threat.iocs.length}):`);
  for (const ioc of threat.iocs) {
    console.log(`  [${ioc.ioc_type}] ${ioc.value}`);
  }
}

// Usage
checkAndEnrich('latinum-wallet-mcp', 'pypi');
```