Cryptography API - SCANOSS documentation

ComponentAlgorithms

Retrieves cryptographic algorithms detected in a single software component.

HTTP Request Example

# Get cryptographic algorithms for a component
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq

Response Examples

Successful Response

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "requirement": ">=5.0.0",
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}

Error Response — Component Not Found

{
  "component": {
    "purl": "pkg:github/unknown/component",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Component not found in database",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}

Error Response — Invalid PURL

{
  "component": {
    "purl": "invalid-purl-format",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Invalid PURL format provided",
    "error_code": "INVALID_PURL"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}

Error Handling

Component responses include optional error fields when issues occur during processing:

error_message: Human-readable description of the error
error_code: Machine-readable error code for programmatic handling

Error Codes

Code	Description
`INVALID_PURL`	The provided PURL format is invalid
`COMPONENT_NOT_FOUND`	The component was not found in the database
`NO_INFO`	No cryptographic information is available for the component
`INVALID_SEMVER`	The provided version requirement is invalid

When a component-level error occurs, the overall response status remains "SUCCESS" because the request itself was processed successfully. Component-level errors are indicated within the individual component object.

ComponentsAlgorithms

Retrieves cryptographic algorithms detected across multiple software components in a single request.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq

Response Examples

Successful Response

{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        },
        {
          "algorithm": "RSA",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/scanoss/scanoss.py",
      "requirement": "~1.30.0",
      "version": "v1.30.0",
      "algorithms": [
        {
          "algorithm": "SHA-256",
          "strength": "Strong"
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}

Mixed Response with Error

{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/unknown/component",
      "requirement": ">=1.0.0",
      "version": "",
      "algorithms": [],
      "error_message": "Component not found in database",
      "error_code": "COMPONENT_NOT_FOUND"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Batch request processed"
  }
}

ComponentAlgorithmsInRange

Analyses a single software component across a specified version range and returns all cryptographic algorithms detected, along with the versions in which each algorithm appears. Use this endpoint to audit cryptographic changes across a component’s release history.

HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq

Response Format

The response contains the following fields:

component: Contains the component analysis results
- purl: The PURL of the requested component
- versions: Component versions in which at least one cryptographic algorithm was detected
- algorithms: All cryptographic algorithms found across the specified version range
status: Response status indicating success or failure

Each algorithm object contains:

Algorithm name and strength classification
Detection metadata and analysis results

Response Example

Component with Algorithms Across Versions

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions": ["1.0.0", "2.0.0", "3.0.0", "5.0.0"],
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      },
      {
        "algorithm": "MD5",
        "strength": "Weak"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}

Component with No Cryptographic Algorithms

{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "versions": [],
    "algorithms": [],
    "error_message": "Component not found: 'pkg:github/example/simple-utility'",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}

ComponentsAlgorithmsInRange

Analyses multiple software components across specified version ranges and returns cryptographic algorithms for each in a single request.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/range/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq

ComponentVersionsInRange

Analyses a single software component and returns two lists: versions that contain cryptographic algorithms, and versions that do not. Use this endpoint to determine at which point in a component’s release history cryptographic functionality was introduced or removed.

HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/versions/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq

Response Example

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions_with": ["2.0.0", "3.0.0", "4.0.0", "5.0.0"],
    "versions_without": ["1.0.0", "1.5.0"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Version ranges Successfully retrieved"
  }
}

ComponentsVersionsInRange

Batch version of ComponentVersionsInRange - analyzes multiple components and returns version lists based on cryptographic algorithm presence for each component.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/version/range/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq

ComponentHintsInRange

Retrieves cryptographic hints for a component, including detected protocols, libraries, SDKs and frameworks.

HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/cryptography/hints/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq

Response Format

The response contains the following fields:

component: Contains the component analysis results
- purl: The PURL of the requested component
- hints: Cryptographic hints detected in the component
- version: The specific version analysed
status: Response status indicating success or failure

Each hint object contains:

Unique identifier for the hint
Name of the cryptographic entity detected
Description of the detected usage or implementation
Classification of the hint (see categories below)
Reference URL for further information
PURL of the detected entity

Hint Categories

Hints are classified into the following categories:

Category	Description
`protocol`	Cryptographic protocols (e.g. TLS, SSH, HTTPS)
`library`	Cryptographic libraries (e.g. OpenSSL, Bouncy Castle)
`sdk`	Software development kits with cryptographic capabilities
`framework`	Frameworks that include cryptographic functionality

Response Examples

Component with Cryptographic Hints

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "hints": [
      {
        "id": "openssl-hint-001",
        "name": "OpenSSL",
        "description": "Industry standard cryptographic library providing SSL/TLS protocols",
        "category": "library",
        "url": "https://www.openssl.org/",
        "purl": "pkg:generic/openssl@3.0.0"
      },
      {
        "id": "tls-protocol-001",
        "name": "TLS 1.3",
        "description": "Transport Layer Security protocol implementation",
        "category": "protocol",
        "url": "https://tools.ietf.org/html/rfc8446",
        "purl": ""
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}

Component with No Cryptographic Hints

{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "version": "1.0.0",
    "hints": [],
    "error_message": "No info found for: pkg:github/example/simple-utility",
    "error_code": "NO_INFO"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}

ComponentsHintsInRange

Retrieves cryptographic hints for multiple components in a single request, returning the cryptographic protocols, libraries, SDKs and frameworks detected across all specified components.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/cryptography/hints/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq

DownloadRuleset

Download cryptography detection rulesets as compressed .tar.gz archives. Rulesets are used to identify cryptographic algorithms across multiple programming languages and are compatible with tools such as Semgrep and OpenGrep.

Ruleset Types

dca: Deep Code Analysis rules for semantic detection using SCANOSS Crypto Finder
keywords: eyword-based rules for pattern matching

Version Specification

latest: Most recent ruleset release
versioned: Specific release (e.g., v1.2.3)

HTTP Request Examples

# Get DCA ruleset (latest version)
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY"

# Get Keywords ruleset (specific version)
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/keywords/v1.2.3/download' \
  -H "X-Api-Key: $SC_API_KEY"

Response Format

The API returns a binary .tar.gz file. Metadata is included in HTTP response headers.

Example Headers

HTTP/1.1 200 OK
Content-Type: application/gzip
Content-Disposition: attachment; filename="scanoss-crypto-dca-v1.2.3.tar.gz"
X-Ruleset-Name: dca
X-Ruleset-Version: v1.2.3
X-Checksum-SHA256: a3f5d8b9e2c7f1a4b6d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

<binary tarball content>

Download & Extract

# Download directly to file
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY" \
  -o scanoss-crypto-dca-latest.tar.gz

# Extract immediately
tar -xzf scanoss-crypto-dca-latest.tar.gz

Inspect Headers

# Download and capture headers
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY" \
  -D headers.txt \
  -o scanoss-crypto-dca-latest.tar.gz

# View metadata from headers
cat headers.txt

Tarball Structure

dca-v1.2.3/
├── java/                  # Java cryptography detection rules
│   ├── jca.yaml
│   ├── bouncycastle.yaml
│   └── ...
├── python/                # Python cryptography detection rules
│   ├── cryptography.yaml
│   ├── pycrypto.yaml
│   └── ...
├── go/                    # Go cryptography detection rules
│   └── ...
└── manifest.json          # Ruleset metadata and checksums

Manifest

Each ruleset includes a manifest.json file containing metadata:

{
  "name": "dca",
  "version": "v1.2.3",
  "description": "Standard cryptography detection rules (to be used with SCANOSS Crypto Finder)",
  "created_at": "2025-11-10T10:00:00Z",
  "checksum_sha256": "abc123..."
}

​ComponentAlgorithms

​HTTP Request Example

​Response Examples

​Successful Response

​Error Response — Component Not Found

​Error Response — Invalid PURL

​Error Handling

​Error Codes

​ComponentsAlgorithms

​HTTP Request Example

​Response Examples

​Successful Response

​Mixed Response with Error

​ComponentAlgorithmsInRange

​HTTP Request Example

​Response Format

​Response Example

​Component with Algorithms Across Versions

​Component with No Cryptographic Algorithms

​ComponentsAlgorithmsInRange

​HTTP Request Example

​ComponentVersionsInRange

​HTTP Request Example

​Response Example

​ComponentsVersionsInRange

​HTTP Request Example

​ComponentHintsInRange

​HTTP Request Example

​Response Format

​Hint Categories

​Response Examples

​Component with Cryptographic Hints

​Component with No Cryptographic Hints

​ComponentsHintsInRange

​HTTP Request Example

​DownloadRuleset

​Ruleset Types

​Version Specification

​HTTP Request Examples

​Response Format

​Example Headers

​Download & Extract

​Inspect Headers

​Tarball Structure

​Manifest

ComponentAlgorithms

HTTP Request Example

Response Examples

Successful Response

Error Response — Component Not Found

Error Response — Invalid PURL

Error Handling

Error Codes

ComponentsAlgorithms

HTTP Request Example

Response Examples

Successful Response

Mixed Response with Error

ComponentAlgorithmsInRange

HTTP Request Example

Response Format

Response Example

Component with Algorithms Across Versions

Component with No Cryptographic Algorithms

ComponentsAlgorithmsInRange

HTTP Request Example

ComponentVersionsInRange

HTTP Request Example

Response Example

ComponentsVersionsInRange

HTTP Request Example

ComponentHintsInRange

HTTP Request Example

Response Format

Hint Categories

Response Examples

Component with Cryptographic Hints

Component with No Cryptographic Hints

ComponentsHintsInRange

HTTP Request Example

DownloadRuleset

Ruleset Types

Version Specification

HTTP Request Examples

Response Format

Example Headers

Download & Extract

Inspect Headers

Tarball Structure

Manifest