SBOM Endpoints

05 Sep 2023
8 Minutes to read

Print
Dark
Light
PDF

SBOM Endpoints

Updated on 05 Sep 2023
8 Minutes to read

Print
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

Add Component - Add a new component to an existing SBOM.
Create SBOM - Creates a new blank SBOM.
Get Entity Overview For Entity - Returns the overview of a given entity.
Get Metrics For Entity - Returns the metrics for a given entity.
Get Own Organizations - Retrieve data for all of the organizations you are a member of.
Get SBOM - Retrieve one or more SBOMs in the desired format.
Get SBOMs - Retrieve the data of all of the SBOMs in an organization.
Import SBOM - Import an SBOM into an organization from an SBOM file.
Save Confirm SBOM - Finalize the creation of an SBOM.
Update Components - Updates one or more existing components in an SBOM.

Add Component

The v1/project/addComponent endpoint adds a component to an existing SBOM.

Endpoint
v1/project/addComponent
Request Method
POST
Parameter	Description
sbom_id	The ID of the SBOM.
name	The name of the software component that is to be added.
org	(optional) The organization of the software component that is to be added.
version	(optional) The version of the software component that is to be added.
search_results.package.purl	(optional) The PURL of the component.
search_results.repo.repo_url	(optional) The Git repository URL of the component.
search_results.product.cpe	(optional) The CPE of the component.

Request Example:

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
  "id": "",
  "ion_id": "",
  "selected": true,
  "confidence": 0,
  "position": -1,
  "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567",
  "status": "",
  "name": "Software Name",
  "org": "Organization Name",
  "version": "1.0",
  "search_results": {
    "package": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "purl": "pkg:pypi/org/name@1.0"
      }
    ],
    "repo": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "repo_url": "https://github.com/org/name"
      }
    ],
    "product": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "cpe": "cpe:/a:org:name:1.0"
      }
    ]
  }
}
"https://api.ionchannel.io/v1/project/addComponent"

Response Example:

{
  "id": "",
  "ion_id": "",
  "selected": true,
  "confidence": 0,
  "position": -1,
  "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567",
  "status": "",
  "name": "Software Name",
  "org": "Organization Name",
  "version": "1.0",
  "search_results": {
    "package": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "purl": "pkg:pypi/org/name@1.0"
      }
    ],
    "repo": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "repo_url": "https://github.com/org/name"
      }
    ],
    "product": [
      {
        "id": "",
        "confidence": 0,
        "selected": false,
        "name": "Software Name",
        "org": "Organization Name",
        "version": "1.0",
        "is_user_input": true,
        "automatically_selected": false,
        "cpe": "cpe:/a:org:name:1.0"
      }
    ]
  }
}

Create SBOM

The v1/project/createSBOM endpoint creates a new blank SBOM.

Endpoint
v1/project/createSBOM
Request Method
POST
Parameter	Description
name	The name of the SBOM.
version	The version of the SBOM.
supplier	The supplier of the SBOM.
contact_name	The name of the point of contact of the SBOM.
contact_email	The email address of the point of contact of the SBOM.
org_id	The ID of the organization.

Request Example:

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
  "name": "SBOM Name",
  "version": "1.0",
  "supplier": "SBOM Supplier",
  "contact_name": "Contact Name",
  "contact_email": "email@email.com",
  "monitor_frequency": "daily",
  "org_id": "abcd1234-ab12-ab12-ab12-abcde123456",
  "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138"
}' \
"https://api.ionchannel.io/v1/project/createSBOM"

Response Example:

{
  "data": {
    "id": "bcde1234-ab12-ab12-ab12-abcde234567",
    "name": "SBOM Name",
    "version": "1.0",
    "supplier": "SBOM Supplier",
    "contact_name": "Contact Name",
    "contact_email": "email@email.com",
    "monitor_frequency": "daily",
    "status": "created",
    "created_at": "2022-04-21T23:23:16.236918Z",
    "updated_at": "2022-04-21T23:23:16.236918Z",
    "deleted_at": null,
    "entry_count": 0,
    "metadata": {
      "entry_count": 0,
      "resolved_entry_count": 0,
      "partially_resolved_entry_count": 0,
      "unresolved_entry_count": 0
    },
    "metrics": {
      "risk": {
        "score": 0,
        "scopes": {
          "ecosystem": 0,
          "supplyChain": 0,
          "software": 0
        }
      },
      "compliance": {
        "passing": 0,
        "failing": 0
      },
      "resolution": {
        "resolved": 0,
        "partiallyResolved": 0,
        "unresolved": 0
      }
    },
    "entries": null,
    "team_id": "cdef1234-ab12-ab12-ab12-abcde345678",
    "org_id": "abcd1234-ab12-ab12-ab12-abcde123456",
    "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138" }, 
    "meta": {
        "total_count": 0,
        "offset": 0
    }
}

Get Entity Overview For Entity

The v1/score/getEntityOverviewForEntity endpoint takes one or more associated purl and returns the overview of that entity.

Endpoint
v1/score/getEntityOverviewForEntity
Request Method
POST
Parameter	Description
package_id	(optional) The purl of the package (e.g., pkg:github.com/lodash/lodash)
product_id	(optional) The purl of the product (CPE). (e.g., cpe:/a:lodash:lodash:4.17.19::~~~node.js~~)
repo_id	(optional) The purl of the repository (e.g., pkg:npm/lodash/lodash@4.17.19)

Request Example:

curl --location 'https://api.ionchannel.io/v1/score/getEntityOverviewForEntity' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "repo_id": "pkg:github.com/lodash/lodash",
    "package_id": "pkg:npm/lodash/lodash@4.17.19",
    "product_id": "cpe:/a:lodash:lodash:4.17.19::~~~node.js~~"
}'

Response Example:

{
    "data": {
        "id": "pkg:github.com/lodash/lodash",
        "name": "lodash",
        "org": "lodash",
        "version": "4.17.19",
        "sources": [
            {
                "type": "package",
                "source": [
                    "npm"
                ],
                "id": "pkg:npm/lodash/lodash@4.17.19",
                "link": "https://npmjs.com/package/lodash"
            },
            {
                "type": "product",
                "source": [
                    "NVD",
                    "NPM",
                    "Red Hat Security Advisories"
                ],
                "id": "cpe:/a:lodash:lodash:4.17.19::~~~node.js~~",
                "link": "https://nvd.nist.gov/vuln/search/results?adv_search=true&isCpeNameSearch=true&query=cpe:/a:lodash:lodash:4.17.19::~~~node.js~~"
            },
            {
                "type": "package",
                "source": [
                    "github.com"
                ],
                "id": "pkg:github.com/lodash/lodash",
                "link": ""
            }
        ],
        "score": {
            "name": "pkg:github.com/lodash/lodash",
            "value": 64.933221358928,
            "scopes": [
                {
                    "name": "ecosystem",
                    "value": 77.24402043492557
                },
                {
                    "name": "technology",
                    "value": 65.55476604087977
                },
                {
                    "name": "supply_chain",
                    "value": 56.68434311252412
                }
            ]
        },
        "summary": "Metrics indicate that this component has very poorly distributed activity, very few products in its organization, and few releases per month. Therefore, this component may have an associated integration risk.",
        "risk_tags": [
            {
                "name": "integration",
                "description": "Risk arising from difficulty integrating software due to lack of support or responsiveness.",
                "severity": "yellow"
            }
        ]
    },
    "meta": {
        "total_count": 0,
        "offset": 0
    }
}

Get Metrics For Entity

The v1/score/getEntityOverviewForEntity endpoint takes one or more associated purl and returns all of the metric data for that entity.

Endpoint
v1/score/getMetricsForEntity
Request Method
POST
Parameter	Description
package_id	(optional) The purl of the package (e.g., pkg:github.com/lodash/lodash)
product_id	(optional) The purl of the product (CPE). (e.g., cpe:/a:lodash:lodash:4.17.19::~~~node.js~~)
repo_id	(optional) The purl of the repository (e.g., pkg:npm/lodash/lodash@4.17.19)

Request Example:

curl --location 'https://api.ionchannel.io/v1/score/getMetricsForEntity' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "repo_id": "pkg:github.com/lodash/lodash",
    "package_id": "pkg:npm/lodash/lodash@4.17.19",
    "product_id": "cpe:/a:lodash:lodash:4.17.19::~~~node.js~~"
}'

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
  "name": "SBOM Name",
  "version": "1.0",
  "supplier": "SBOM Supplier",
  "contact_name": "Contact Name",
  "contact_email": "email@email.com",
  "monitor_frequency": "daily",
  "org_id": "abcd1234-ab12-ab12-ab12-abcde123456",
  "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138"
}' \
"https://api.ionchannel.io/v1/project/createSBOM"

Response Example:

GetMetricsForEntity.json

Get Own Organizations

The v1/organizations/getOwnOrganizations endpoint returns information on all of the organizations you are a member of and your user role in that organization.

Endpoint
v1/organizations/getOwnOrganizations
Request Method
GET

Request Example:

curl -H "Authorization: Bearer TOKEN" \
"https://api.ionchannel.io/v1/organizations/getOwnOrganizations"

Response Example:

{
  "data": [
    {
      "organization": {
        "id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "created_at": "2022-02-10T00:28:43.283507Z",
        "updated_at": "2022-02-10T00:28:43.283507Z",
        "deleted_at": null,
        "name": "SBOM Name",
        "members": [
          {
            "user_id": "bcde1234-ab12-ab12-ab12-abcde234567",
            "role": "admin"
          }
        ]
      },
      "user_id": "bcde1234-ab12-ab12-ab12-abcde234567",
      "role": "admin"
    }
  ],
  "meta": {
    "total_count": 1,
    "offset": 0
  }
}

Get SBOM

Endpoint
v1/report/getSBOM
Request Method
POST
Parameter	Description
sbom_id	The ID of the SBOM.
sbom_type	The type of SBOM to export. Valid values are SPDX or CycloneDX.
encoding	The encoding of the SBOM. Valid values are CSV, JSON, tag-value, XLSX, XML, and YAML.
include_dependencies	Designates if a project's dependencies should be included in the file. Valid values are true or false.
team_top_level	Designates if the top-level components should be the organization name. The organization name will be used as the top-level component if set to true. If set to false, the SBOM name will be set as the top-level component. This parameter should always be set to true when including multiple SBOMs in the request.

Request Example:

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
  "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567"
}' \
"https://api.ionchannel.io/v1/report/getSBOM?sbom_type=SPDX&include_dependencies=true&team_top_level=false"

Get SBOMs

The v1/project/getSBOMs endpoint returns data on all of an organization's SBOMs.

Endpoint
v1/project/getSBOMs
Request Method
GET
Parameter	Description
org_id	The ID of the organization. See Get Own Organizations for obtaining an Organization ID.

Request Example:

curl -H "Authorization: Bearer TOKEN" \
"https://api.ionchannel.io/v1/project/getSBOMs?org_id=ORG_ID"

Response Example:

{
  "data": {
    "id": "abcd1234-ab12-ab12-ab12-abcde123456",
    "organization": {
      "risk": {
        "score": 58,
        "scopes": {
          "ecosystem": 90,
          "supplyChain": 65,
          "software": 20
        }
      },
      "compliance": {
        "passing": 24,
        "failing": 6
      },
      "resolution": {
        "resolved": 12,
        "partiallyResolved": 10,
        "unresolved": 8
      }
    },
    "softwareLists": [
      {
        "id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "name": "SBOM Name",
        "version": "1.0",
        "supplier": "SBOM Supplier",
        "contact_name": "Contact Name",
        "contact_email": "email@email.com",
        "monitor_frequency": "daily",
        "status": "allconfirmed",
        "created_at": "2022-04-14T17:08:50.20362Z",
        "updated_at": "2022-04-14T17:21:18.006804Z",
        "deleted_at": null,
        "entry_count": 30,
        "metadata": {
          "entry_count": 30,
          "resolved_entry_count": 12,
          "partially_resolved_entry_count": 10,
          "unresolved_entry_count": 8
        },
        "metrics": {
          "risk": {
            "score": 49,
            "scopes": {
              "ecosystem": 90,
              "supplyChain": 65,
              "software": 20
            }
          },
          "compliance": {
            "passing": 24,
            "failing": 6
          },
          "resolution": {
            "resolved": 12,
            "partiallyResolved": 10,
            "unresolved": 8
          }
        },
        "entries": null,
        "team_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "org_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138"
      }
    ]
  },
  "meta": {
    "total_count": 0,
    "offset": 0
  }
}

Import SBOM

The v1/project/importSBOM endpoint allows you to import an SBOM into an organization from an SBOM file.

Endpoint
v1/project/importSBOM
Request Method
POST
Parameter	Description
sbom_id	The SBOM ID.

Request Example:

curl -X POST \                                                                     
-H "Authorization: Bearer TOKEN" \
-F 'file=@/path/to/file' \
"https://api.ionchannel.io/v1/project/importSBOM?sbom_id=SBOM_ID"

Response Example:

{
  "data": {
    "id": "bcde1234-ab12-ab12-ab12-abcde234567",
    "name": "SBOM Name",
    "version": "1.0",
    "supplier": "SBOM Supplier",
    "contact_name": "Contact Name",
    "contact_email": "email@email.com",
    "monitor_frequency": "daily",
    "status": "created",
    "created_at": "2022-04-18T22:40:59.782503Z",
    "updated_at": "2022-04-18T22:40:59.782503Z",
    "deleted_at": null,
    "entry_count": 1,
    "metadata": {
      "entry_count": 1,
      "resolved_entry_count": 0,
      "partially_resolved_entry_count": 0,
      "unresolved_entry_count": 1
    },
    "metrics": {
      "risk": {
        "score": 0,
        "scopes": {
          "ecosystem": 0,
          "supplyChain": 0,
          "software": 0
        }
      },
      "compliance": {
        "passing": 0,
        "failing": 0
      },
      "resolution": {
        "resolved": 0,
        "partiallyResolved": 0,
        "unresolved": 0
      }
    },
    "entries": [
      {
        "id": "defg1234-ab12-ab12-ab12-defgh456789",
        "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "name": "requirements.txt",
        "org": "",
        "version": "",
        "status": "no-resolution",
        "search_results": {
          "package": [],
          "product": [],
          "repo": []
        },
        "suggestions": null,
        "error_message": "",
        "created_at": "2022-04-18T22:42:02.188993Z",
        "updated_at": "2022-04-18T22:42:02.188993Z",
        "deleted_at": null
      }
    ],
    "team_id": "cdef1234-ab12-ab12-ab12-abcde345678",
    "org_id": "abcd1234-ab12-ab12-ab12-abcde123456",
    "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138"
  },
  "meta": {
    "total_count": 1,
    "offset": 0
  }
}

Save Confirm SBOM

The v1/project/saveConfirmSBOM updates the status of the SBOM to Finished.

Endpoint
v1/project/saveConfirmSBOM
Request Method
POST
Parameter	Description
id	The SBOM ID

Request Example:

curl -X POST \
-H "Authorization: Bearer TOKEN" \
"https://api.ionchannel.io/v1/project/saveConfirmSBOM?id=SBOM_ID"

Response Example:

{
  "data": {
    "id": "bcde1234-ab12-ab12-ab12-abcde234567"
  },
  "meta": {
    "total_count": 1,
    "offset": 0
  }
}

Update Components

The v1/project/updateComponents updates one or more components in an existing SBOM.

Endpoint
v1/project/updateComponents
Request Method
POST
Parameter	Description
id	The component ID
sbom_id	The ID of the SBOM
project_id	The ID of the project (if any)

Request Example:

curl --location --request POST 'https://api.ionchannel.io/v1/project/updateComponents' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "name": "Component Name",
        "version": "1.0.0",
        "org": "Organization",
        "status": "no_resolution",
        "search_results": {
            "package": [
                {
                    "purl": "pkg:type/organization/component_name@1.0.0",
                    "selected": true
                }
            ],
            "repo": [
                {
                    "repo_url": "https://github.com/organization/repository",
                    "selected": true
                }
            ],
            "product": [
                {
                    "cpe": "cpe:/a:organization:component_name:1.0.0:-",
                    "selected": true
                }
            ]
        },
        "suggestions": null,
        "created_at": "2023-02-13T23:05:09.307727Z",
        "updated_at": "2023-02-13T23:05:09.980529Z",
        "deleted_at": null,
        "error_message": "",
        "position": 0
    }
]'

Response Example:

{
  "data": [
    {
      "id": "abcd1234-ab12-ab12-ab12-abcde123456",
      "sbom_id": "bcde1234-ab12-ab12-ab12-abcde234567",
      "project_id": null,
      "name": "Component Name",
      "version": "1.0.0",
      "org": "Organization",
      "status": "resolved",
      "search_results": {
        "package": [
          {
            "id": "4e4f9df6-fd44-46d9-929e-0db513dcda1b",
            "confidence": 0,
            "is_user_input": true,
            "selected": true,
            "automatically_selected": false,
            "name": "",
            "org": "",
            "version": "",
            "purl": "pkg:type/organization/component_name@1.0.0"
          }
        ],
        "repo": [
          {
            "id": "04dc943f-bb97-4554-819d-b8758456361c",
            "confidence": 0,
            "is_user_input": true,
            "selected": true,
            "automatically_selected": false,
            "name": "",
            "org": "",
            "version": "",
            "repo_url": "https://github.com/organization/repository"
          }
        ],
        "product": [
          {
            "id": "e802193d-61e1-45b9-b5c1-c8f26ef0715a",
            "confidence": 0,
            "is_user_input": true,
            "selected": true,
            "automatically_selected": false,
            "name": "",
            "org": "",
            "version": "",
            "cpe": "cpe:/a:organization:component_name:1.0.0:-"
          }
        ]
      },
      "suggestions": [
        {
          "key": "name",
          "value": ""
        },
        {
          "key": "org",
          "value": ""
        },
        {
          "key": "version",
          "value": ""
        }
      ],
      "created_at": "2023-02-14T00:00:30.226593Z",
      "updated_at": "2023-02-14T00:06:36.625413Z",
      "deleted_at": null,
      "error_message": ""
    }
  ],
  "meta": {
    "total_count": 0,
    "offset": 0
  }
}

Was this article helpful?

What's Next

User and Team Endpoints

Table of contents