Scanning API

Provides high-precision scanning of folder structures to identify software components based on project hierarchy, file names, and content patterns.

FolderHashScan

Scan folder structures to identify software components using hierarchical proximity hashing.

The scan evaluates filenames, directory structure, and file content to generate similarity scores against the SCANOSS knowledge base.

Request Format

The request defines a hierarchical folder tree:

• root: The root folder node containing the structure to scan
  • path_id: Folder identifier (can be obfuscated)
  • sim_hash_names: Hash derived from filenames
  • sim_hash_content: Hash derived from file contents
  • sim_hash_dir_names: Hash derived from directory structure
  • lang_extensions: File type distribution (e.g., {“py”: 15, “js”: 8})
  • children: Nested folder nodes following the same structure

Optional filtering parameters:

• rank_threshold: Filter by ecosystem (e.g. github, npm, maven)
• category: Filter by ecosystem (e.g. github, npm, maven)
• query_limit: Max results per folder
• recursive_threshold: Minimum score for recursive matches
• min_accepted_score: Minimum similarity score (0–1)

HTTP Request Example

```bash
curl -X POST 'https://api.scanoss.com/v2/scanning/hfh/scan' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "root": {
      "path_id": "src",
      "sim_hash_names": "abc123def456",
      "sim_hash_content": "789ghi012jkl",
      "sim_hash_dir_names": "345mno678pqr",
      "lang_extensions": {
        "py": 25,
        "md": 3
      },
      "children": [
        {
          "path_id": "src/utils",
          "sim_hash_names": "def456ghi789",
          "sim_hash_content": "012jkl345mno",
          "sim_hash_dir_names": "678pqr901stu",
          "lang_extensions": {
            "py": 8
          },
          "children": []
        }
      ]
    },
    "rank_threshold": 5,
    "category": "github",
    "query_limit": 10,
    "min_accepted_score": 0.7
  }' | jq

Response Format

Returns scan results grouped by folder path.

• results: List of folder paths with their matching components
• status: Response status indicating success or failure

Each result includes:

• path_id: The folder path identifier from the request
• components: List of matching components found in this folder

Each component includes:

• purl: Component Package URL
• name: Component name
• vendor: Component maintainer or organisation
• versions: Matched versions with similarity scores
• rank: Component quality rank (1–9)
• order: Match priority (1 = best match)

Response Example

Successful Scan with Matches

{
  "results": [
    {
      "path_id": "src",
      "components": [
        {
          "purl": "pkg:github/scanoss/scanoss.py",
          "name": "scanoss-py",
          "vendor": "scanoss",
          "versions": [
            {
              "version": "1.30.0",
              "score": 0.95,
              "licenses": [
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            },
            {
              "version": "1.29.0",
              "score": 0.87,
              "licenses": [
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            }
          ],
          "rank": 1,
          "order": 1
        },
        {
          "purl": "pkg:github/example/similar-project",
          "name": "similar-project",
          "vendor": "example",
          "versions": [
            {
              "version": "2.1.0",
              "score": 0.78,
              "licenses": [
                {
                  "name": "Apache License 2.0",
                  "spdx_id": "Apache-2.0",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/Apache-2.0.html"
                },
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            }
          ],
          "rank": 3,
          "order": 2
        }
      ]
    },
    {
      "path_id": "src/utils",
      "components": [
        {
          "purl": "pkg:pypi/requests",
          "name": "requests",
          "vendor": "psf",
          "versions": [
            {
              "version": "2.31.0",
              "score": 0.92,
              "licenses": [
                {
                  "name": "Apache License 2.0",
                  "spdx_id": "Apache-2.0",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/Apache-2.0.html"
                }
              ]
            }
          ],
          "rank": 1,
          "order": 1
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Scan completed successfully"
  }
}

Scan with No Matches

{
  "results": [],
  "status": {
    "status": "SUCCESS",
    "message": "Scan completed successfully"
  }
}

Match Quality

Rank (1-9)

Indicates confidence in component origin:

• 1-2: Official or highly trusted repositories
• 3-4: Verified community projects
• 5-6: Standard open-source projects
• 7-9: Lower confidence or derivative matches

Score (0-1)

Similarity confidence per version:

• 0.9-1.0: Very high confidence
• 0.8-0.89: High confidence
• 0.7-0.79: Moderate confidence
• Below 0.7: Low confidence (filterable via min_accepted_score)