FossID Documentation

FossID Workbench 25.1

New API “components->get_usage”

Added new API “components->get_usage” which returns a list of scans where a component is used as identification or dependency.

Get the list of users assigned a specific role or permission

Added the possibility to get the list of users assigned a specific role or permission by using existing API action “users->get_all_users” with new optional parameters “role_id” or “permission_code”. Please note that permission USERS_ASSIGN_PERMISSIONS is required.

List permissions and roles for each user

Added the possibility to list permissions and roles for each user by sending “searched_username” optional parameter to APIs: “users->get_user_roles_list” and “users->get_user_permissions_list”.

Vulnerabilities count in API response “components->list_components”

Include information about component vulnerabilities count in API response “components->list_components” by adding 4 new fields: critical_vulnerability_count, high_vulnerability_count, medium_vulnerability_count, low_vulnerability_count.

Added new “type” value in API “users->check_status”: “EXTRACT_ARCHIVES”.

Added new API actions: “logs->get_list”, “logs->get_actions_list”.

Changed error response in order to support multiple fields errors in API “licenses->create” and “licenses->update”. Example of the new response:

{
  "operation": "licenses_create",
  "status": "0",
  "data": [
    {
      "code": "Legacy.controller.licenses.name_already_exists",
      "message": "License already exists with that name.",
      "message_parameters": {
        "fieldname": "license_name",
        "value": "MIT License"
      }
    },
    {
      "code": "Legacy.controller.licenses.identifier_already_exists",
      "message": "License already exists with that identifier.",
      "message_parameters": {
        "fieldname": "license_identifier",
        "value": "MIT"
      }
    }
  ],
  "error": "Legacy.controller.licenses.identifier_already_exists",
  "message": "License already exists with that identifier.",
  "message_parameters": []
}

Fixed bug: API “scans → get_identified_files” does not include license text when “exclude_file_license_text=0” and “new_output_format=1”

Fixed bug: API “files_and_folders->get_fossid_results” returns scan_id value “0” always.

Fixed bug: API “scans->get_scan_comments” returns only records marked “only_include_in_report”

Added new option “include_dep_det_info” only for Excel reports, to the scans/projects -> generate_report action

"include_dep_det_info: "Optional, only for Excel reports, default false if not set.
        Specify if dependency tab has to contain detailed information string, 
        example: Scope: devDependencies  Project: NPM:json-diff:0.5.5 => NPM::mocha:1.7.4 =>"
        
#### New notice file: aggregate level.
There is a new "type" optional parameter in actions "scans->notice_extract_run", "scans->notice_extract_view_status" and "scans->notice_extract_download"
Default value is **NOTICE_EXTRACT_FILE** in order to maintain backward compatibility.
```plaintext
{
  "group": "scans",
  "action": "notice_extract_run",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scan_code": "scan_code",
    "type": "NOTICE_EXTRACT_COMPONENT or NOTICE_EXTRACT_FILE or NOTICE_EXTRACT_AGGREGATE"
  }
}

Improved error message clarity for API action “scans->get_scan_comments” when handling absence of scan_code values.

Old response example

{
  "operation": "scans_get_scan_comments",
  "status": "0",
  "data": null,
  "error": "Scan code is required.",
  "message": "Scan code is required.",
  "message_parameters": []
}

New response example

{
  "operation": "scans_get_scan_comments",
  "status": "0",
  "data": [
    {
      "code": "RequestData.Base.mandatory_field_missing",
      "message": "The mandatory field scan_code is missing; string is required",
      "message_parameters": {
        "fieldname": "scan_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []

New option were added to the request in API action “scans->get_scan_comments”

Old request example

{
  "group": "scans",
  "action": "get_scan_comments",
  "data": {
    "username": "username",
    "key": "user key",
    "scan_code": "scan_code",
    "only_include_in_report": "Optional, Default: true",
    "only_important": "Optional, Default: false"
  }
}

New request example

{
  "group": "scans",
  "action": "get_scan_comments",
  "data": {
    "username": "username",
    "key": "user key",
    "scan_code": "scan_code",
    "only_include_in_report": "Optional, Default: true",
    "only_important": "Optional, Default: false",
    "include_scan_component_comment": "Optional, Default: true"     
  }
}

New fields were added to response in API action “components->list_components”

Old response example

{
  "operation": "components_list_components",
  "status": "1",
  "data": [
     {
        "id": 3,
        "version": "1.1",
        "name": "ofp",
        "cpe": "cpe:2.3:a:ansi-regex_project:ansi-regex:1.1.1:*:*:*:*:node.js:*:*",
      }
    ]
  }
}

New response example

{
  "operation": "components_list_components",
  "status": "1",
  "data": [
     {
        "id": 3,
        "version": "1.1",
        "name": "ofp",
        "cpe": "cpe:2.3:a:ansi-regex_project:ansi-regex:1.1.1:*:*:*:*:node.js:*:*",
        "license_name": "BSD 3-Clause \"New\" or \"Revised\" License",
        "license_identifier": "BSD-3-Clause",
        "license_category": "UNCATEGORIZED",
        "intake_status": "pending",
        "critical_vulnerability_count": 0,
        "high_vulnerability_count": 3,
        "medium_vulnerability_count": 0,
        "low_vulnerability_count": 0,
        "created": "2024-11-21 00:39:46",
        "updated": "2024-11-21 00:39:46"
      }
    ]
  }
}

FossID Workbench 24.3

License category identifier “NON_COMMERCIAL” was replaced with “SOURCE_AVAILABLE_NC” in order to align with the label used in UI.

Improved error message clarity for API action “scans->run” when handling invalid specific_code values.

Old response example

{
  "operation": "scans_run",
  "status": "0",
  "data": [
    {
      "code": "RequestData.RunRequest.specific_code_is_not_a_valid_scan_code",
      "message": "null is not a valid scan code",
      "message_parameters": {
        "specific_code": "null"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

New response example

{
  "operation": "scans_run",
  "status": "0",
  "data": [
    {
      "code": "RequestData.RunRequest.specific_code_is_not_a_valid_scan_code",
      "message": "not_existing is not a valid scan code",
      "message_parameters": {
        "specific_code": "not_existing"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

Changed response: removed values with numeric keys for API action “component_approval->list_scans_with_component”

Old response example

{
  "operation": "component_approval_list_scans_with_component",
  "status": "1",
  "data": [
    {
      "0": "11",
      "1": "Scan Name",
      "2": "api_test_component_approval_2",
      "3": "2024-10-10",
      "4": "test_project_component_approval_2",
      "5": "test_project_component_approval_2",
      "scan_id": "11",
      "name": "Scan Name",
      "code": "api_test_component_approval_2",
      "scan_created": "2024-10-10",
      "project_name": "test_project_component_approval_2",
      "project_code": "test_project_component_approval_2"
    }
  ]
}

New response example

{
  "operation": "component_approval_list_scans_with_component",
  "status": "1",
  "data": [
    {
      "scan_id": "11",
      "name": "Scan Name",
      "code": "api_test_component_approval_2",
      "scan_created": "2024-10-10",
      "project_name": "test_project_component_approval_2",
      "project_code": "test_project_component_approval_2"
    }
  ]
}

Improvements in error messages

For example now when status is 0 the data field may contain an array of errors. Before:

{
  "operation": "policy_management_create_policy_rule",
  "status": "0",
  "data": {
    "type": "license_category",
    "condition": "UNCATEGORIZED"
  },
  "error": "Handler.project.policy_management.rule_already_exist",
  "message": "This policy rule already exists in this project\nlicense_category\nUNCATEGORIZED",
  "message_parameters": []
}

Now:

{
  "operation": "policy_management_create_policy_rule",
  "status": "0",
  "data": [
    {
      "code": "Handler.project.policy_management.rule_already_exist",
      "message": "This policy rule already exists in this project",
      "message_parameters": {
        "fieldname": "license_category",
        "value": "UNCATEGORIZED"
      }
    }
  ],
  "error": "Handler.project.policy_management.rule_already_exist",
  "message": "This policy rule already exists in this project",
  "message_parameters": []
}

New notice file: component level.

There is a new “type” optional parameter in actions “scans->notice_extract_run”, “scans->notice_extract_view_status” and “scans->notice_extract_download” Default value is NOTICE_EXTRACT_FILE in order to maintain backward compatibility.

{
  "group": "scans",
  "action": "notice_extract_run",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scan_code": "scan_code",
    "type": "NOTICE_EXTRACT_COMPONENT or NOTICE_EXTRACT_FILE"
  }
}

Pagination added to action scans->get_marked_as_identified_files

Optional parameters were added to help with pagination:

count_results:    Return number of components. Boolean (0 default, 1)
records_per_page: Number of records per page. If empty components will not be paginated
page:             Current page, if empty assume the first page

Pagination added to action scans->get_identified_files

Optional parameters were added to help with pagination:

count_results:    Return number of components. Boolean (0 default, 1)
records_per_page: Number of records per page. If empty components will not be paginated
page:             Current page, if empty assume the first page

Added new API to download local / matched remote scan files

Request for local scan file

{
    "group": "download",
    "action": "download_scan_local_file",
    "data": {
        "username": "fossid",
        "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "file_path": "Rm9zc0lELnBocA==",
        "scan_id": "19"
    }
}

Request for matched remote file

{
    "group": "download",
    "action": "download_scan_remote_file",
    "data": {
        "username": "fossid",
        "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "match_file_id": "ZWU2MGI0YTVkNGNmMGRmYzI1MjVkMzA0MDAwMDAwMDA=",
        "scan_id": "19"
    }
}

Vulnerabilities

New UI page for Vulnerabilities was added together with equivalent API actions. Please check API docs for detailed information.

Vulnerabilities API Docs

New API action to retrieve project component comments: projects->get_project_component_comment

Request

{
  "group": "projects",
  "action": "get_project_component_comment",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "project_id": "project id ",
    "component_id": "component id"
  }
}

Experimental upper case “Components” API group which was visible only in API test but not in documentation was removed as announced in “Future Release Advisory” section of the release 24.1 and calling now API with group “Components” or “components” is the same.

FossID Workbench 24.2

Added new optional fields ‘match_filtering_threshold’ and ‘advanced_match_scoring‘ to API group ‘scans’, action ‘run’.

Both fields are enabled by default.

New request

{
    "group": "scans"
    "action": "run"
    "data": {
        "username": "username"
        "key": "user key"
        "scan_code": "Code of the scan"
        "limit": "Limit on number of FossID results. Default/Recommended: 10"
        "sensitivity": "Sensitivity of the scan. Default/Recommended: 10. A value lower than 6 (0-5) will result in only full file matches being returned"
        "replace_existing_identifications": "Replace existing identifications. Boolean (0 default,1)"
        "reuse_identification": "If exists, try to use an existing identification depending on parameter ‘identification_reuse_type’. Boolean (0 default,1)"
        "identification_reuse_type": "Last identification found will be used for files with the same hash. Values: any, only_me, specific_project, specific_scan"
        "specific_code": "Optional, only when ‘identification_reuse_type’ is ‘specific_project’ or ‘specific_scan’"
        "auto_identification_detect_declaration": "Automatically detect license declaration inside files. Boolean (0 default,1)"
        "auto_identification_detect_copyright": "Automatically detect copyright statements inside files. Boolean (0 default,1)"
        "auto_identification_resolve_pending_ids": "Automatically resolve pending identifications. Boolean (0 default,1)"
        "scan_failed_only": "If true, this will only scan files that have failed in the previous scan. Boolean (0 default,1)"
        "delta_only": "Only newly added files or modified files will be scanned. Boolean (0,1 default)"
        "full_file_only": "Will result in only full file matches being returned regardless of sensitivity setting. Boolean (0 default,1)"
        "match_filtering_threshold": "Minimum length (in characters) of snippet to be considered valid after applying intelligent match filtering. Set to 0 to disable intelligent match filtering for current scan. If parameter is not sent it defaults to value of ‘webapp_match_filtering_threshold‘ from fossid.conf. If there is no value in fossid.conf the default is 300 characters."
        "advanced_match_scoring": "If true, scan will run with advanced match scoring. When no value is provided, the default behaviour is enabled. Boolean (0,1 default)"
    }
}

Changed response for API call group: quick_scan, action: scan_one_file (renamed `classification` field into `noise`)

Old response example

{
    "operation": "quick_scan_scan_one_file",
    "status": "1",
    "data": [{
        "component": {},
        "classification": [], ...
    }]
}

New response example

{
    "operation": "quick_scan_scan_one_file",
    "status": "1",
    "data": [{
        "component": {},
        "noise": {}, ...
    }]
}

Changed response for API endpoints:

group: files_and_folders, action: get_fossid_results

group: scans, action: get_scan_file_info

Old response example

{
    "operation": "files_and_folders_get_fossid_results",
    "status": "1",
    "data": {
        "99": {
            "id": 99,
            "classification": "[]" ...
        }
    }
}

New response example

{
    "operation": "files_and_folders_get_fossid_results",
    "status": "1",
    "data": {
         "99": {
            "id": 99,
            "classification": "{}", ...
         }
    }
}

Old response example

{
    "operation": "scans_get_scan_file_info",
    "status": "1",
    "data": {
        "fossid_results": {
            "99": {
                "id": 99,
                "classification": "[]" ...
            }
        }
    }
}

New response example

{
    "operation": "scans_get_scan_file_info",
    "status": "1",
    "data": {
        "fossid_results": {
            "99": {
                "id": 99,
                "classification": "{}" ...
            }
        }
    }
}

Changed API call group: components, action: search_cpe

old request:

{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "%android"
    }
}

new request:

{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "Required, example: 'node' ",
        "version": "Optional, component version, example: '4.5.0' ",
        "limit": "Optional, limit of the search results, Default 30"
    }
}

Changed response, removed values with numeric keys, for API endpoints:

group: files_and_folders, action: get_identification

group: files_and_folders, action: get_folder_content_metrics

group: licenses, action: get_information

group: projects, action: get_all_scans

group: scans, action: get_folder_metrics

group: scans, action: get_scan_identified_components

Old response example

{
  "operation": "files_and_folders_get_folder_content_metrics",
  "status": "1",
  "data": {
    "0": "0",
    "1": "0",
    "2": "0",
    "3": "0",
    "total": "0",
    "pending_identification": "0",
    "identified_files": "0",
    "without_matches": "0"
  },
  "message": "Success"
}

New response example

{
  "operation": "files_and_folders_get_folder_content_metrics",
  "status": "1",
  "data": {
    "total": "0",
    "pending_identification": "0",
    "identified_files": "0",
    "without_matches": "0"
  },
  "message": "Success"
}

Changes in API call group ‘scans’ action ‘download_content_from_git’

In 24.1 API docs 2 fields were added by mistake to download_content_from_git. This is fixed in 24.2, the information regarding git branch and repo is saved during scans->create action

FossID Workbench 24.1

Added new option field ‘remove_dependency_request’ to API group ‘component_approval’ action ‘delete_requests_for_unidentified’

Old request

{
  "group": "component_approval",
  "action": "delete_requests_for_unidentified",
  "data": {
    "username": "username",
    "key": "user key",
    "project_code": "My project code"
  }
}

New request

{
  "group": "component_approval",
  "action": "delete_requests_for_unidentified",
  "data": {
    "username": "username",
    "key": "user key",
    "project_code": "My project code",
    "remove_dependency_request": "Optional. Deletes dependency components approval requests. Boolean (0 default, 1)"
  }
}

Added new options to API group ‘projects’ action ‘get_project_components’

Old request

{
    "group": "projects",
    "action": "get_project_components",
    "data": {
        "username": "username",
        "key": "user key",
        "project_code": "My project code"
    }
}

New request

{
    "group": "projects",
    "action": "get_project_components",
    "data": {
        "username": "username",
        "key": "user key",
        "project_code": "My project code",
        "count_results":"Return number of components. Boolean (0 default, 1)"
        "records_per_page":"Number of records per page. If empty components will not be paginated"
        "page":"Current page, if empty assume the first page"
    }
}

If option “count_results” is “1”

{
  "operation": "projects_get_project_components",
  "status": "1",
  "data": {
    "count_results": 18
  }
}

Changed response for API endpoint to get list of project components.

Old response: list of components contains only components that were use as identifications in the project scans.

New response: list of components includes components from identification plus components from dependencies.

New field ‘Origin’ was added to the response to differentiate components. The value could be: dependency or identified

{
  "operation": "projects_get_project_components",
  "status": "1",
  "data": {
    "2": {
      "id": 2,
      "created_by": 1,
      "cpe": null,
      "name": "coffee-script",
      "version": "1.12.7",
      "purl": "pkg:npm/coffee-script@1.12.7",
      "purl_type": "npm",
      "purl_namespace": null,
      "purl_name": "coffee-script",
      "purl_version": "1.12.7",
      "url": "http://coffeescript.org",
      "release_date": null,
      "built_date": null,
      "supplier_name": null,
      "supplier_url": "",
      "community_url": "",
      "download_url": "https://registry.npmjs.org/coffee-script/-/coffee-script-1.12.7.tgz",
      "download_url_binary": null,
      "md5": null,
      "sha1": "c05dae0cb79591d05b3070a8433a98c9a89ccc53",
      "sha256": null,
      "binary_md5": null,
      "binary_sha1": null,
      "binary_sha256": null,
      "license_id": 583,
      "comment": "Component created by WebApp from dependency analysis results.",
      "description": "Unfancy JavaScript",
      "package_size": null,
      "package_size_binary": null,
      "platform": null,
      "image_id": null,
      "repository_download_path_binary": null,
      "programming_language": null,
      "commits_nro": null,
      "contributors_nro": null,
      "releases_nro": null,
      "bugs_nro": null,
      "fixed_bugs_nro": null,
      "community_status": null,
      "community_size": null,
      "copyright": null,
      "attribution_acknowledgement": null,
      "warranty_liability_exclusions": null,
      "known_bugs": null,
      "known_vulnerabilities": null,
      "change_log": null,
      "kb_origin": 0,
      "created": "2024-01-09 13:42:03",
      "updated": "2024-01-09 13:42:03",
      "license_identifier": "MIT",
      "license_name": "MIT License",
      "origin": "dependency",
      "project_comment": "some comment about project"
    }
  }
}

Added new actions to components group of API endpoints

action: update_cpe_list:

{
    "group": "components",
    "action": "update_cpe_list",
    "data": {
        "username": "username",
        "key": "user key",
        "url": "Optional (one of url or base64file must be included): Url from where to download the CPE dictionary, eg https:\/\/nvd.nist.gov\/feeds\/xml\/cpe\/dictionary\/official-cpe-dictionary_v2.3.xml.gz",
        "base64file": "Optional (one of url or base64file must be included): base64 encoded gzipped CPE dictionary in xml format (cat official-cpe-dictionary_v2.3.xml | gzip | base64 w0). This may be useful for offline installations"
    }
}

action: search_cpe:

{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "Required: Mysql pattern. See https:\/\/dev.mysql.com\/doc\/refman\/8.0\/en\/pattern-matching.html",
        "version": "Optional: Mysql pattern. See https:\/\/dev.mysql.com\/doc\/refman\/8.0\/en\/pattern-matching.html"
    }
}

Changed API endpoint to create a component: added possibility to insert all existing fields

Old request:

{
    "group": "components",
    "action": "create",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Component Name",
        "version": "Component Version",
        "purl": "Package URL",
        "url": "Component URL",
        "license_identifier": "Component license Identifier",
        "sup_com_name": "Name for the supplier or community of the component.",
        "supplier_url": "URL for the supplier of the component.",
        "community_url": "URL for the community of the component.",
        "download_url": "Download URL of the component.",
        "package_md5": "MD5 for the component package.",
        "package_sha1": "SHA1 for the component package.",
        "comment": "Desired comment for the component."
    }
}

New request with all fields:

{
    "group": "components",
    "action": "create",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Required: Exact name of the component.",
        "version": "Required: Exact version of the component.",
        "license_identifier": "Required: Valid SPDX identifier, see license group",
        "purl": "Optional. Package URL",
        "url": "Optional. Component URL",
        "cpe": "Optional. CPE 2.3 identifier",
        "package_size": "Optional",
        "package_size_binary": "Optional",
        "commits_nro": "Optional",
        "contributors_nro": "Optional",
        "releases_nro": "Optional",
        "bugs_nro": "Optional",
        "fixed_bugs_nro": "Optional",
        "community_size": "Optional",
        "sup_com_name": "Optional. Name for the supplier or community of the component.",
        "supplier_url": "Optional. URL for the supplier of the component.",
        "community_url": "Optional. URL for the community of the component.",
        "download_url": "Optional. Download URL of the component.",
        "download_url_binary": "Optional",
        "comment": "Optional. Desired comment for the component.",
        "description": "Optional",
        "repository_download_path_binary": "Optional",
        "copyright": "Optional",
        "attribution_acknowledgement": "Optional",
        "warranty_liability_exclusions": "Optional",
        "known_bugs": "Optional",
        "known_vulnerabilities": "Optional",
        "change_log": "Optional",
        "platform": "Optional",
        "programming_language": "Optional",
        "package_md5": "Optional. MD5 for the component package.",
        "binary_md5": "Optional",
        "package_sha1": "Optional. SHA1 for the component package.",
        "binary_sha1": "Optional",
        "sha256": "Optional",
        "binary_sha256": "Optional",
        "release_date": "Optional",
        "community_status": "Optional"
    }
}

Changed API endpoint to update a component: added possibility to edit all existing fields

Old request:

{
    "group": "components",
    "action": "update",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Component Name",
        "version": "Component Version",
        "purl": "Package URL",
        "url": "Component URL",
        "license_identifier": "Component license Identifier",
        "sup_com_name": "Name for the supplier or community of the component.",
        "supplier_url": "URL for the supplier of the component.",
        "community_url": "URL for the community of the component.",
        "download_url": "Download URL of the component.",
        "package_md5": "MD5 for the component package.",
        "package_sha1": "SHA1 for the component package.",
        "comment": "Desired comment for the component."
    }
}

New request with all fields:

{
    "group": "components",
    "action": "update",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Required: Exact name of the component.",
        "version": "Required: Exact version of the component.",
        "new_name": "Optional",
        "new_version": "Optional",
        "license_identifier": "Required: Valid SPDX identifier, see license group",
        "purl": "Optional. Package URL",
        "url": "Optional. Component URL",
        "cpe": "Optional. CPE 2.3 identifier",
        "package_size": "Optional",
        "package_size_binary": "Optional",
        "commits_nro": "Optional",
        "contributors_nro": "Optional",
        "releases_nro": "Optional",
        "bugs_nro": "Optional",
        "fixed_bugs_nro": "Optional",
        "community_size": "Optional",
        "sup_com_name": "Optional. Name for the supplier or community of the component.",
        "supplier_url": "Optional. URL for the supplier of the component.",
        "community_url": "Optional. URL for the community of the component.",
        "download_url": "Optional. Download URL of the component.",
        "download_url_binary": "Optional",
        "comment": "Optional. Desired comment for the component.",
        "description": "Optional",
        "repository_download_path_binary": "Optional",
        "copyright": "Optional",
        "attribution_acknowledgement": "Optional",
        "warranty_liability_exclusions": "Optional",
        "known_bugs": "Optional",
        "known_vulnerabilities": "Optional",
        "change_log": "Optional",
        "platform": "Optional",
        "programming_language": "Optional",
        "package_md5": "Optional. MD5 for the component package.",
        "binary_md5": "Optional",
        "package_sha1": "Optional. SHA1 for the component package.",
        "binary_sha1": "Optional",
        "sha256": "Optional",
        "binary_sha256": "Optional",
        "release_date": "Optional",
        "community_status": "Optional"
    }
}

Changed response for API endpoint to get list of components

Old response:

{
  "operation": "components_list_components",
  "status": "1",
  "data": {
    "1": {
      "id": "1",
      "name": "antlr/antlr",
      "version": "2.7.7"
    },
    "2": {
      "id": "2",
      "name": "com.github.ben-manes.caffeine/caffeine",
      "version": "2.8.8"
    },
    ...
}

New response:

{
  "operation": "components_list_components",
  "status": "1",
  "data": [
    {
      "id": 1316,
      "name": "@types/babel-types",
      "version": "7.0.15",
      "cpe": null
    },
    {
      "id": 1317,
      "name": "@types/babylon",
      "version": "6.16.9",
      "cpe": null
    },
    ...
}

Changed response for API endpoint to get component information, removed values with numeric keys

Old response example:

{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    "0": "451",
    "1": "2022-09-12 20:11:17",
    "2": "2022-09-12 20:11:17",
    "3": "1",
    "4": null,
    "5": "abbrev",
    "6": "1.1.1",
    "7": null,
    "8": null,
    "9": null,
    "10": null,
    "11": null,
    "12": "https://github.com/isaacs/abbrev-js#readme",
    "13": null,
    "14": "",
    "15": "",
    "16": "",
    "17": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
    "18": null,
    "19": null,
    "20": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "21": null,
    "22": null,
    "23": null,
    "24": null,
    "25": "483",
    "26": "Component created by WebApp from dependency analysis results.",
    "27": "Like ruby's abbrev module, but in js",
    "28": null,
    "29": null,
    "30": null,
    "31": null,
    "32": null,
    "33": null,
    "34": null,
    "35": null,
    "36": null,
    "37": null,
    "38": null,
    "39": null,
    "40": null,
    "41": null,
    "42": null,
    "43": null,
    "44": null,
    "45": null,
    "46": null,
    "47": "0",
    "48": "2022-09-12",
    "49": null,
    "50": "483",
    "51": "ISC License",
    "52": "ISC",
    "53": "fossid",
    "id": "451",
    "created": "2022-09-12 20:11:17",
    "updated": "2022-09-12 20:11:17",
    "created_by": "1",
    "cpe": null,
    "name": "abbrev",
    "version": "1.1.1",
    "purl": null,
    "purl_type": null,
    "purl_namespace": null,
    "purl_name": null,
    "purl_version": null,
    "url": "https://github.com/isaacs/abbrev-js#readme",
    "release_date": null,
    "supplier_name": "",
    "supplier_url": "",
    "community_url": "",
    "download_url": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
    "download_url_binary": null,
    "md5": null,
    "sha1": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "sha256": null,
    "binary_md5": null,
    "binary_sha1": null,
    "binary_sha256": null,
    "license_id": "483",
    "comment": "Component created by WebApp from dependency analysis results.",
    "description": "Like ruby's abbrev module, but in js",
    "package_size": null,
    "package_size_binary": null,
    "platform": null,
    "image_id": null,
    "repository_download_path_binary": null,
    "programming_language": null,
    "commits_nro": null,
    "contributors_nro": null,
    "releases_nro": null,
    "bugs_nro": null,
    "fixed_bugs_nro": null,
    "community_status": null,
    "community_size": null,
    "copyright": null,
    "attribution_acknowledgement": null,
    "warranty_liability_exclusions": null,
    "known_bugs": null,
    "known_vulnerabilities": null,
    "change_log": null,
    "kb_origin": "0",
    "created_date": "2022-09-12",
    "component_release_date": null,
    "license_name": "ISC License",
    "license_identifier": "ISC",
    "user_username": "fossid"
  }
}

New response example:

{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    "id": 394,
    "created_by": 1,
    "cpe": null,
    "name": "abbrev",
    "version": "1.1.1",
    "purl": "pkg:npm/abbrev@1.1.1",
    "purl_type": null,
    "purl_namespace": null,
    "purl_name": null,
    "purl_version": null,
    "url": "",
    "release_date": null,
    "supplier_name": "",
    "supplier_url": "",
    "community_url": "",
    "download_url": "",
    "download_url_binary": "",
    "md5": null,
    "sha1": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "sha256": null,
    "binary_md5": "",
    "binary_sha1": "",
    "binary_sha256": "",
    "license_id": 541,
    "comment": "",
    "description": "Like ruby's abbrev module, but in js",
    "package_size": null,
    "package_size_binary": null,
    "platform": "",
    "image_id": null,
    "repository_download_path_binary": "",
    "programming_language": "",
    "commits_nro": null,
    "contributors_nro": null,
    "releases_nro": null,
    "bugs_nro": null,
    "fixed_bugs_nro": null,
    "community_status": "",
    "community_size": null,
    "copyright": null,
    "attribution_acknowledgement": "",
    "warranty_liability_exclusions": "",
    "known_bugs": "",
    "known_vulnerabilities": "",
    "change_log": "",
    "kb_origin": null,
    "created": "2024-01-09 14:22:07",
    "updated": "2024-01-09 14:22:07",
    "user_username": "fossid",
    "license_identifier": "ISC",
    "license_name": "ISC License",
    "license_category": "PERMISSIVE",
    "created_date": "2024-01-09",
    "component_release_date": null
  }
}

Removed duplicate information in responses for the next API endpoints:

group: users, action: assign_permission

group: users, action: assign_role

group: scans, action: archive_scan

group: scans, action: ignore_rules_add

group: scans, action: ignore_rules_show

group: scans, action: ignore_rules_delete

group: scans, action: add_scan_specific_component_comment

group: scans, action: remove_scan_specific_component_comment

group: scans, action: string_match_rules_add

group: scans, action: refresh_files

group: component_approval, action: delete_requests_for_unidentified

group: component_approval, action: reset_request_by_component

Old response:

{
    "operation": "operation name",
    "status": "1",
    "data": {
        "operation": "operation name",
        "status": "1",
        "data": null,
        "message": "Response message"
    },
    "message": "Response message"
}

New response:

{
    {
      "operation": "operation name",
      "status": "1",
      "data": null,
      "message": "Response message"
    }
}

Since 23.3 the validation for scans -> create/update actions, field jar_file_extraction, is strict and does not allow empty string.

Only valid options or explicit null will pass the validation, accepted values: always, never, if_no_fullmatch.

FossID Workbench 23.3

New API endpoints to create project management policy rule

{
    "group": "policy_management",
    "action": "create_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)",
        "description": "Optional",
        "action": "policy rule type,(generate_warning)"
    }
}

New API endpoints to update project management policy rule

{
    "group": "policy_management",
    "action": "update_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)",
        "description": "Optional",
        "action": "policy rule type,(generate_warning)"
    }
}

New API endpoints to delete project management policy rule

{
    "group": "policy_management",
    "action": "delete_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id"
    }
}

New API endpoints to get project policy management rule

{
    "group": "policy_management",
    "action": "get_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id"
    }
}

New API endpoints to get project policy management rule by condition

{
    "group": "policy_management",
    "action": "get_policy_rule_by_condition",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)"
    }
}

New API endpoints to delete all project policy management rules

{
    "group": "policy_management",
    "action": "delete_all_policy_rules",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get list of all project policy management rules

{
    "group": "policy_management",
    "action": "get_policy_rules_list",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get project policy management warnings info

{
    "group": "projects",
    "action": "get_policy_warnings_info",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get policy management warnings counter by folder or file path

{
    "group": "scans",
    "action": "get_policy_warnings_by_path",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code",
        "path": "Path to the folder or file in base64"
    }
}

New API endpoints to get quantity scan project policy warnings

{
    "group": "scans",
    "action": "get_policy_warnings_counter",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code"
    }
}

New API endpoints to get policy management warnings information for given scan

{
    "group": "scans",
    "action": "get_policy_warnings_info",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code"
    }
}

Added fields to response from ‘projects’ -> ‘list_projects’

API call:

{
    "group": "projects",
    "action": "list_projects",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
}

Old response:

{
    "operation": "projects_list_projects",
    "status": "1",
    "data": [
        {
            "id": 1,
            "project_code": "test_1",
            "project_name": "test"
        }
    ]
}

New response:

{
    "operation": "projects_list_projects",
    "status": "1",
    "data": [
        {
          "id": 1,      
          "creator": 1,
          "project_code": "test_1",
          "project_name": "test",
          "limit_date": null,
          "product_code": "",
          "product_name": "",
          "description": "",
          "comment": "",
          "is_archived": false,
          "jira_project_key": "",
          "created": "2023-08-16 11:45:18",
          "updated": null,
          "scans": "int, number of the project scans",
          "policy_rules": "int, number of the project rules",
          "warnings": "int, number of the warnings",
        }
    ]
}

FossID Workbench 23.2

Backward incompatible changes

Stricter permissions for assigning a scan to a project

A user needs to be a project member or to have PROJECT_UPDATE_ANY permission in order to be able to assign a scan to a project when using actions scans -> create or scans -> update.

New API endpoints to retrieve and generate and set API keys for users

This API action retrieves the API keys of the user with the username searched_username.

{
    "group": "users",
    "action": "get_api_key",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "searched_username": "Username for the user being searched."
    }

This API action generates a new API keys and assigns it to the user with the username searched_username.

{
    "group": "users",
    "action": "renew_api_key",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "searched_username": "Username for the user being searched."
    }
}

New API endpoints to create/update/delete component approval comments

{
    "group": "component_approval",
    "action": "list_comments",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "component_id": "Component id"
    }
}

{
    "group": "component_approval",
    "action": "create_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "component_id": "Legacy.view.apipusher.comment_id",
        "comment_text": "Comment content."
    }
}

{
    "group": "component_approval",
    "action": "update_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "comment_id": "Legacy.view.apipusher.comment_id",
        "comment_text": "Comment content."
    }
}

{
    "group": "component_approval",
    "action": "delete_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "comment_id": "Legacy.view.apipusher.comment_id"
    }
} 

FossID Workbench 23.1

Backward incompatible changes

The API endpoint to download scan reports was removed. The new API group “download” was added to download reports

{
  {
    "group": "download",
    "action": "download_report",
    "data": {
        "username": "username",
        "key": "user_key",
        "report_entity" : "`scans` or `projects`"
        "process_id": "process_id",
    }
  }
} 

New API endpoints regarding new feature: Project level reports

1. The new API endpoint to create project level reports

{
    "group": "projects",
    "action": "generate_report",
    "data": {
        "username": "username",
        "key": "user_key",
        "project_code": "My project code",
        "report_type": "xlsx or spdx or dynamic",
        "selection_type": "include_foss",
        "selection_view" :"",
        "async" : "0 or 1",
        "report_content_type" :"default or abbreviated"
    }
}

2. The new API endpoint to check the status of generating project level reports process

{
    "group": "projects",
    "action": "check_status",
    "data": {
        "username": "username",
        "key": "user_key",
        "type": "Type of the process - `REPORT_GENERATION`"
        "process_id": "Id of the process"
    }
}

Trigger async reports generation from API

The scans report type ‘basic’ was added to the list of reports that could be generated asynchronously using action “scans” -> “generate_report”.

New field `purl` in components -> create and components -> update

New field purl was added to store Package URL information associated with a component. You can read more about PackageURL specification here: https://github.com/package-url/purl-spec

Example creating a component:

{
    "group": "components",
    "action": "create",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "aaaa",
        "version": "2",
        "license_identifier": "MIT",
        "purl": "pkg:npm/ansi-regex@5.0.1"
    }
}

Inside components table the value from purl field is parsed and also stored in individual columns, so in the output from components -> get_information several other fields can be seen alongside with purl:

{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    ....
    "id": 1,
    "created": "2023-01-15 03:36:19",
    "updated": "2023-01-15 03:36:19",
    "created_by": 1,
    "cpe": null,
    "name": "json-diff",
    "version": "1.0.0",
    "purl": "pkg:github/andreyvit/json-diff@1.0.0",
    "purl_type": "github",
    "purl_namespace": "andreyvit",
    "purl_name": "json-diff",
    "purl_version": "1.0.0",
    "url": "https://github.com/andreyvit/json-diff/archive/v1.0.0.tar.gz",
   ...
  }
}

New API endpoints for updating dependencies scans -> update_dependency_analysis_results

Also existing API endpoint “add_dependency_analysis_result” received an optional field “include_in_report”. Default value being 1.

{
    "group": "scans",
    "action": "update_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Component Version",
        "package_id": "Purl string",
        "projects_and_scopes": "Optional JSON object",
        "detailed_dependency_info": "Optional JSON object",
        "include_in_report": "Possible value 1 or 0"
    }
}

FossID Workbench 22.2

Boolean values returned in fields from scans -> get_information

The fields listed below which returned in the past: null, 0 or 1 will return from now on null, false or true:

is_archived

is_blind_audit

is_from_report

has_file_extension

{
    "group": "scans",
    "action": "get_information",
    "data": {
        "username": "test_user",
        "key": "test_user_key",
        "scan_code": "test_scan"
    }
}

{
  "operation": "scans_get_information",
  "status": "1",
  "data": {
    "id": 1950,
    "scanlimit": 10,
    "last_run": null,
    "code": "test_scan_code",
     ...
    "is_from_report": false,      <==
    "has_file_extension": true,   <==
     ...
    "user_id": 1,
    "project_id": 1
  }
}

API endpoints to add and remove dependencies to scans

Two new actions under “scans” group allows adding and removing dependencies:

{
    "group": "scans",
    "action": "add_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Component Version",
        "package_id": "Purl string",
        "projects_and_scopes": "Optional JSON object",
        "detailed_dependency_info": "Optional JSON object",
        "include_in_report": "Possible value 1 or 0"
    }
}

{
    "group": "scans",
    "action": "remove_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Legacy.view.apipusher.my_component_version"
    }
}

Improvement: Using wrong username or key when calling API is not returning meaningful error message

In the past a generic error would be displayed if wrong username or key was used:

{
    "group": "Components",
    "action": "update",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "new_empty_comp",
        "version": "1",
        "new_name": "",
        "new_version": ""
    }
}

{
  "operation": "Components_update",
  "status": "0",
  "data": null,
  "error": "An error occurred. Please check WebApp logs.",
  "message": "An error occurred. Please check WebApp logs.",
  "message_parameters": []
}

The new message helps identify the issue:

{
  "operation": "Components_update",
  "status": "0",
  "data": [],
  "error": "Classes.FossID.user_not_found_or_api_key_is_not_correct",
  "message": "User is not found or API key is incorrect",
  "message_parameters": []
}

New optional field ‘new_project_owner’ in action ‘projects’ -> ‘update’

The ‘project creator’ concept proved to not be flexible enough to handle all situations, for this reason in 22.2 it is replaced with ‘project owner’. The owner can be changed by admin (user with permission PROJECT_UPDATE_ANY) while with the creator this was not possible. For backward compatibility reasons the ‘creator’ field will be kept when creating a project. While for update there is a new optional field ‘new_project_owner’ which allows changing the owner of a project with a different user.

{
    "group": "projects",
    "action": "update",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "project_some_code",
        "project_name": "project_some_name",
        ....
        "new_project_owner": "username of new owner"
    }
}

Trigger async reports generation from API

Until now reports generation using action “scans” -> “generate_report” was a synchronous operation. In WebApp 22.2 was introduced a method of asynchronously generating reports from API. This is a 3 steps action:

Call action “scans” -> “generate_report” with new parameter async=1. This request will return a “process_id” value to used in next step
Call action “scans” -> “check_status” passing process_id value and also setying type “REPORT_GENERATION”
When the check_status indicates status FINISHED call newly added action “scans” -> “download_report” passing scan_id and process_id.

Changed errors and messages

Due to code refactoring or just to improve the information some errors and messages were changed:

1. projects -> delete

API call:

{
    "group": "projects",
    "action": "delete",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code"

    }
}

Old response

{
  "operation": "projects_delete",
  "status": "1",
  "data": {
    "operation": "delete",
    "status": "1",
    "data": null,
    "message": "Project has been deleted successfully",
    "error": ""
  },
  "message": "Project has been deleted successfully"
}

New response

{
  "operation": "projects_delete",
  "status": "1",
  "data": null,
  "message": "Project has been deleted successfully"
}

2. projects -> delete with missing field ‘project_code’

API call:

{
    "group": "projects",
    "action": "delete",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code"
    }
}

Old response

{
  "operation": "projects_delete",
  "status": "0",
  "data": null,
  "error": "Field 'project_code': the provided value  does not meet number of characters requirements.",
  "message": "Field 'project_code': the provided value  does not meet number of characters requirements.",
  "message_parameters": []
}

New response

{
  "operation": "projects_delete",
  "status": "0",  
  "data": [
    {
      "code": "RequestData.Base.invalid_field_length",
      "message": "Field 'project_code': the provided value  does not meet number of characters requirements.",
      "message_parameters": {
        "fieldname": "project_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

3. projects -> create or update with missing field ‘project_code’ or “project_name”

API call:

{
    "group": "projects",
    "action": "create",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_name": "pr_code",
        ....

    }
}

Old response

{
   "operation":"projects_create",
   "status":"0",
   "data":null,
   "error":"Project code is required.",
   "message":"Project code is required.",
   "message_parameters":[
      
   ]
}

New response

{
  "operation": "projects_create",
  "status": "0",
  "data": [
    {
      "code": "RequestData.Base.mandatory_field_missing",
      "message": "The mandatory field project_code is missing; string is required",
      "message_parameters": {
        "fieldname": "project_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
} 

4. projects -> assign member

API call:

{
    "group": "projects",
    "action": "assign_member",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code",
        "assign_member": "fossid"
    }
}

Old response

{
    "operation": "projects_assign_member",
    "status": "1",
    "data": {
        "operation": "assign_member",
        "status": "1",
        "data": null,
        "message": "User fossid has been assigned to project pr_code"
    },
    "message": "User fossid has been assigned to project pr_code"
}

New response

{
    "operation": "projects_assign_member",
    "status": "1",
    "data": null,
    "message": "User fossid has been assigned to project pr_code"
}

5. projects -> remove member

API call:

{
    "group": "projects",
    "action": "remove_member",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code",
        "assign_member": "fossid"
    }
}

Old response

{
    "operation": "projects_remove_member",
    "status": "1",
    "data": {
        "operation": "remove_member",
        "status": "1",
        "data": null,
        "message": "User fossid has been removed from project pr_code"
    },
    "message": "User fossid has been removed from project pr_code"
}

New response

{
    "operation": "projects_remove_member",
    "status": "1",
    "data": null,
    "message": "User fossid has been removed from project pr_code"
}

6. scans -> delete

Scan delete process is background since 23.1 The Action adds a background job and returns a process_id number. When the background job execution is finished the scan is considered deleted.

Old response

{
   {
      "operation": "scans_delete",
      "status": "1",
      "data": "id of the deleted scan",
      "message": "Scan name: 4285 has been deleted."
   }
}

New response

{
  "operation": "scans_delete",
  "status": "1",
  "data": {
    "process_id": integer
  },
  "message": "Scan: scan_name was added in the queue to delete"
}

Use action check_status with the type DELETE_SCAN and process_id to check if the scan has been deleted.

API call:

{
    "group": "scans",
    "action": "check_status",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "Must be empty if type is `DELETE_SCAN`",
        "type": "DELETE_SCAN",
        "delay_response": "Optional: Amount of seconds to wait before response. Max 10.",
        "process_id": "Id of the process"
    }
}

Response example if the process is running

{
  "operation": "scans_check_status",
  "status": "1",
  "data": {
    "process_id": "Id of the process - integer",
    "progress_state": "RUNNING",
    "process_requested": "2023-04-03 13:28:34",
    "process_started": "2023-04-03 13:28:40",
    "process_exited": null
  },
  "message": "Delete scan process is RUNNING"
}

Response example if the process is FINISHED

{
  "operation": "scans_check_status",
  "status": "1",
  "data": true,
  "message": "Scan was deleted successfully"
}

Workbench API Changelog

FossID Workbench 25.1

New API “components->get_usage”

Get the list of users assigned a specific role or permission

List permissions and roles for each user

Vulnerabilities count in API response “components->list_components”

Added new “type” value in API “users->check_status”: “EXTRACT_ARCHIVES”.

Added new API actions: “logs->get_list”, “logs->get_actions_list”.

Changed error response in order to support multiple fields errors in API “licenses->create” and “licenses->update”. Example of the new response:

Fixed bug: API “scans → get_identified_files” does not include license text when “exclude_file_license_text=0” and “new_output_format=1”

Fixed bug: API “files_and_folders->get_fossid_results” returns scan_id value “0” always.

Fixed bug: API “scans->get_scan_comments” returns only records marked “only_include_in_report”

Added new option “include_dep_det_info” only for Excel reports, to the scans/projects -> generate_report action

Improved error message clarity for API action “scans->get_scan_comments” when handling absence of scan_code values.

Old response example

New response example

New option were added to the request in API action “scans->get_scan_comments”

Old request example

New request example

New fields were added to response in API action “components->list_components”

Old response example

New response example

FossID Workbench 24.3

License category identifier “NON_COMMERCIAL” was replaced with “SOURCE_AVAILABLE_NC” in order to align with the label used in UI.

Improved error message clarity for API action “scans->run” when handling invalid specific_code values.

Old response example

New response example

Changed response: removed values with numeric keys for API action “component_approval->list_scans_with_component”

Old response example

New response example

Improvements in error messages

New notice file: component level.

Pagination added to action scans->get_marked_as_identified_files

Pagination added to action scans->get_identified_files

Added new API to download local / matched remote scan files

Vulnerabilities

New API action to retrieve project component comments: projects->get_project_component_comment

Experimental upper case “Components” API group which was visible only in API test but not in documentation was removed as announced in “Future Release Advisory” section of the release 24.1 and calling now API with group “Components” or “components” is the same.

FossID Workbench 24.2

Added new optional fields ‘match_filtering_threshold’ and ‘advanced_match_scoring‘ to API group ‘scans’, action ‘run’.

Both fields are enabled by default.

New request

Changed response for API call group: quick_scan, action: scan_one_file (renamed classification field into noise)

Old response example

New response example

Changed response for API endpoints:

group: files_and_folders, action: get_fossid_results

group: scans, action: get_scan_file_info

Old response example

New response example

Old response example

New response example

Changed API call group: components, action: search_cpe

old request:

new request:

Changed response, removed values with numeric keys, for API endpoints:

group: files_and_folders, action: get_identification

group: files_and_folders, action: get_folder_content_metrics

group: licenses, action: get_information

group: projects, action: get_all_scans

group: scans, action: get_folder_metrics

group: scans, action: get_scan_identified_components

Old response example

New response example

Changes in API call group ‘scans’ action ‘download_content_from_git’

In 24.1 API docs 2 fields were added by mistake to download_content_from_git. This is fixed in 24.2, the information regarding git branch and repo is saved during scans->create action

FossID Workbench 24.1

Added new option field ‘remove_dependency_request’ to API group ‘component_approval’ action ‘delete_requests_for_unidentified’

Old request

New request

Added new options to API group ‘projects’ action ‘get_project_components’

Old request

New request

If option “count_results” is “1”

Changed response for API endpoint to get list of project components.

Old response: list of components contains only components that were use as identifications in the project scans.

New response: list of components includes components from identification plus components from dependencies.

New field ‘Origin’ was added to the response to differentiate components. The value could be: dependency or identified

Added new actions to components group of API endpoints

action: update_cpe_list:

Changed response for API call group: quick_scan, action: scan_one_file (renamed `classification` field into `noise`)

New field `purl` in components -> create and components -> update