Skip to content

timesys.vigiles packages

timesys.vigiles.cves module

timesys.vigiles.cves.get_cve_info(cve_id, fields=None)

Get CVE info by CVE ID

  • Parameters:

    • cve_id (str) -- A valid CVE ID

    • fields (list of str , optional) -- Limit cve data returned to given the fields. If none are specified, all are returned.

      Valid fields: "affected_configurations", "assigner", "description", "identifier", "impact", "modified", "problem_types", "published", "references" , "nvd_status", "cisa", "epss"

  • Returns: CVE data, optionally filtered to the requested fields

  • Return type: dict

timesys.vigiles.cves.search_cves_by_product(cpe_product, version='', ids_only=False)

Get CVEs which affect given CPE Product and optionally filter by version

  • Parameters:
    • product (str) -- CPE Product (package_name) to search CVEs for
    • version (str , optional) -- Version of the product to filter results by, else all affected versions
    • ids_only (bool) -- Return list of CVE identifiers only, no descriptions. Default: False

  • Returns: A list of CVE ids is returned if "ids_only" is true, otherwise a dictionary with CVE identifier keys and description values

  • Return type: list or dict

timesys.vigiles.cves.set_status(scope, cve_id, package_name, status, justification=None, justification_detail=None, package_version=None, manifest_tokens=None, group_tokens=None)

timesys.vigiles.manifests module

timesys.vigiles.manifests.delete_manifest(manifest_token, confirmed=False)

Delete a manifest with the given token

This action can not be undone. It requires passing True for the 'confirmed' keyword parameter to prevent accidental use.

  • Parameters: manifest_token (str) -- Token of the manifest to be deleted

  • Returns: success : True or False depending on result of operation

  • Return type: dict

Notes

This action can not be undone!

timesys.vigiles.manifests.get_latest_report(manifest_token, filter_results=False, extra_fields=None)

Download the latest report for a manifest with the given token.

  • Parameters:

    • manifest_token (str) -- Token of the manifest for which to fetch the latest report
    • filter_results (bool) -- apply all filters to report if True, else only config filters. Default: False

    • extra_fields (list of str , optional) -- Optionally extend CVE data included in report with any of the following fields:

      "assigner", "description", "impact", "modified", "problem_types", "published", "references"

  • Returns: Results of scan with keys:

    manifest_token : Token of the manifest which was scanned

    group_token : Token of the group that the manifest belongs to

    folder_token : Token of the folder that the manifest belongs to

    cves : list of dictionaries containing information about CVEs found in the scan, also referred to as the "report."

    counts : Dictionary containing CVE counts with keys: : "fixed", "kernel", "toolchain", "unapplied", "unfixed", "upgradable", "whitelisted"

    date : Date the scan was performed

    group_path : URL where the group can be viewed on the web.

    report_path : URL where the report can be viewed on the web. The report token may also be split from the end of this string.

  • Return type: dict

timesys.vigiles.manifests.get_manifest_file(manifest_token, sbom_format=None, file_format=None, sbom_version=None)

Get manifest data as a file

Response does not include other metadata such as group/folder tokens.

  • Parameters:

    • sbom_format (str , optional) -- If specified, the server will convert the manifest data to this format.

      Acceptable formats are:

      spdx: Convert the manifest to SPDX format

      spdx-lite: Convert the manifest to a SPDX tag-value format

      cyclonedx: Convert the manifest to CycloneDX JSON format

    • file_format (str , optional) -- Specify file format type for SPDX and CycloneDX SBOMs

    • sbom_version (str , optional) -- Specify SBOM version for SPDX and CycloneDX SBOMs

  • Returns: The raw manifest file bytes

  • Return type: bytes

timesys.vigiles.manifests.get_manifest_info(manifest_token, sbom_format=None, file_format=None, sbom_version=None)

Get manifest data along with metadata

  • Parameters:

    • sbom_format (str , optional) -- If specified, the server will convert the manifest data to this format.

      Acceptable formats are:

      spdx: Convert the manifest to SPDX format

      spdx-lite: Convert the manifest to a SPDX tag-value format

      cyclonedx: Convert the manifest to CycloneDX JSON format

    • file_format (str , optional) -- Specify file format type for SPDX and CycloneDX SBOMs

    • sbom_version (str , optional) -- Specify SBOM version for SPDX and CycloneDX SBOMs

  • Returns: Result of the request with keys:

    manifest_token: Token representing the manifest

    manifest_name: Name of the manifest with the given token

    folder_token: Token representing a Folder the manifest belongs to

    group_token: Token representing a Group the manifest belongs to

    upload_date: Date the manifest was uploaded

    manifest_data: Contents of the manifest By default this is the same format as it was uploaded, unless converted using the "sbom_format" parameter

  • Return type: dict

timesys.vigiles.manifests.get_manifests()

Get all manifests that are accessible by the current user

Group or folder tokens can be configured to limit results, but only one may be provided. If configured on the llapi object, folder token takes precedence.

  • Returns:

    Each manifest in the returned list is a dictionary with the following keys:

    manifest_name : Name of the manifest

    manifest_token : Token representing the manifest

    group_token : Token representing the Group which the manifest belongs to

    folder_token : Token representing the Folder which the manifest belongs to

    upload_date : Date the manifest was uploaded

  • Return type: list of dict

timesys.vigiles.manifests.get_report_tokens(manifest_token)

Get a list of report_tokens available for the given manifest_token

  • Parameters:

    manifest_token (str) -- Token of the manifest for which to retrieve a list of available reports

  • Returns: A dictionary with meta info about the requested manifest and a list of report info dictionaries, each of which contain the keys:

    "created_date", "report_token", "manifest_token", "manifest_version"

  • Return type: dict

timesys.vigiles.manifests.rescan_manifest(manifest_token, rescan_only=False, filter_results=False, extra_fields=None)

Generate a new report for the given manifest_token

  • Parameters:

    • manifest_token (str) -- Token for the manifest to rescan
    • rescan_only (bool) -- If True, rescan the manifest but not return the report data Default: False
    • filter_results (bool) -- Apply all filters to report if True, else only config filters if available. Default: False

    • extra_fields (list of str , optional) -- Optionally extend CVE data included in report with any of the following fields:

      "assigner", "description", "impact", "modified", "problem_types", "published", "references"

  • Returns: Results of scan with keys:

    manifest_token : Token of the manifest which was scanned

    group_token : Token of the group that the manifest belongs to

    folder_token : Token of the folder that the manifest belongs to

    cves : list of dictionaries containing information about CVEs found in the scan, also referred to as the "report."

    counts : Dictionary containing CVE counts with keys: : "fixed", "kernel", "toolchain", "unapplied", "unfixed", "upgradable", "whitelisted"

    date : Date the scan was performed

    report_path : URL where the report can be viewed on the web. The report token may also be split from the end of this string.

  • Return type: dict

timesys.vigiles.manifests.set_custom_score(manifest_token, product_name, cve_id, custom_score, product_version=None)

Set cve custom score in manifest chain.

  • Parameters:
    • manifest_token (str) -- Token of the manifest used to set a custom score on the related chain
    • product_name (str) -- Target CPE Product (package_name) name
    • cve_id (str) -- CVE ID for which you would like to set a custom score
    • custom_score (str) -- custom score value to set
    • product_version (str , optional) -- Target product version

  • Returns: success

    True or False depending on result of operation

  • Return type: dict

timesys.vigiles.manifests.upload_manifest(manifest, kernel_config=None, uboot_config=None, manifest_name=None, subfolder_name=None, filter_results=False, extra_fields=None, upload_only=False, ecosystems=None, subscribe=None)

Upload and scan (optionally) a manifest

If a group_token is configured on the llapi object, it will be used as the upload location. Otherwise, the default is "Private Workspace."

If both a group_token and folder_token are configured on the llapi object, the folder will be the upload location.

A subfolder name can optionally be supplied in order to upload to or create a folder under the configured group and folder. This will then be the upload target for the given manifest. This is not supported for "Private Workspace".

  • Parameters:

    • manifest (str) -- String of manifest data to upload
    • kernel_config (str , optional) -- Kernel config data used to filter out CVEs which are irrelevant to the built kernel
    • uboot_config (str , optional) -- Uboot config data used to filter out CVEs which are irrelevant to the built bootloader
    • manifest_name (str , optional) -- Name to give the new manifest. If not provided, one will be generated and returned.
    • subfolder_name (str , optional) -- If given, a new folder will be created with this name under the configured group or folder, and the manifest will be uploaded to this new folder. If the subfolder already exists, it will be uploaded there. Not supported for "Private Workspace" Group.
    • filter_results (bool) -- True to apply all configured filters to scan results, False to apply only kernel and uboot config filters. Default: False Note: These filters are configured through the Vigiles web interface.

    • extra_fields (list of str , optional) -- Optionally extend CVE data included in report with any of the following fields:

      "assigner", "description", "impact", "modified", "problem_types", "published", "references"

    • upload_only (bool) -- If true, do not generate an initial CVE report for the uploaded manifest Default: False

    • subscribe (str , optional) -- If provided, the user will be subscribed to the notifications at the given frequency One of "none", "daily", "weekly", or "monthly"

  • Returns: Results of scan with keys:

    manifest_token : Token of the manifest which was scanned

    group_token : Token of the group that the manifest belongs to

    folder_token : Token of the folder that the manifest belongs to

    cves : list of dictionaries containing information about CVEs found in the scan, also referred to as the "report."

    counts : Dictionary containing CVE counts with keys:

    "fixed", "kernel", "toolchain", "unapplied", "unfixed", "upgradable", "whitelisted"

    date : Date the scan was performed

    report_path : URL where the report can be viewed on the web. The report token may also be split from the end of this string.

    exported_manifest : The manifest data in SPDX format

  • Return type: dict

timesys.vigiles.manifests.bulk_move_manifests(sbom_tokens, target_group_token=None, target_folder_token=None, include_history=False)

Move multiple SBOMs to a group/folder

  • Parameters:
    • sbom_tokens (list of str) -- List of SBOM tokens to move
    • target_group_token (str , optional) -- Target group token to which the SBOMs are to be moved, by default None
    • target_folder_token (str , optional) -- Target folder token to which the SBOMs are to be moved, by default None
    • include_history (bool , optional) -- Include previous versions of the SBOM, by default False

  • Returns: success

    True or False depending on result of operation

  • Return type: dict

timesys.vigiles.manifests.bulk_copy_manifests(sbom_tokens, target_group_token=None, target_folder_token=None, include_history=False)

Copy multiple SBOMs to a group/folder

  • Parameters:
    • sbom_tokens (list of str) -- List of SBOM tokens to copy
    • target_group_token (str , optional) -- Target group token to which the SBOMs are to be copied, by default None
    • target_folder_token (str , optional) -- Target folder token to which the SBOMs are to be copied, by default None
    • include_history (bool , optional) -- Include previous versions of the SBOM, by default False

  • Returns: success

    True or False depending on result of operation

  • Return type: dict

timesys.vigiles.groups module

timesys.vigiles.groups.add_group_member(group_token, member_email, role, access_subgroups=False)

Adds a new member to the specified group.

  • Parameters:
    • group_token (str) -- Token of the group to which the member is to be added
    • member_email (str) -- Email address of the member to be added
    • role (str) -- Role to assign to the new member
    • access_subgroups (bool , optional) -- If True, user will be allowed access to all the subgroups of the specified group

  • Raises: Exception -- If any of the required parameters (group_token, member_email, or role) is not provided

  • Returns:

    message: str : Success message on successfuly adding the user

    status_code: int : Status code

  • Return type: dict

timesys.vigiles.groups.create_group(group_name, group_description=None, group_token=None)

Create a new group for the current user

  • Parameters:
    • group_name (str) -- Name for the new group
    • group_description (str , optional) -- Description for the new group
    • group_token (str , optional) -- If group to be created is a subgroup, provide group token of parent group

  • Returns:

    name : Name of group

    description : Description of group

    token : Token of the new group

  • Return type: dict

timesys.vigiles.groups.delete_group(group_token)

Deletes a given group/subgroup

  • Parameters: group_token (str) -- Token of the group to be deleted
  • Raises: Exception -- If no group_token is provided

  • Returns:

    message: str : Success message on successful deletion

    status_code: int : Status code

  • Return type: dict

timesys.vigiles.groups.get_group_info(group_token=None, subgroups=False)

Get group information from a group_token

If a token is passed, it will be used. If no token is passed, but a group_token is configured on the llapi object, it will be used. If neither are provided, an Exception will be raised.

  • Parameters:
    • group_token (str , optional) -- Token of the group to retrieve info for
    • subgroups (bool , optional) -- Set this to True to include subgroup details, default is False

  • Returns:

    name : Group name

    description : Group description

    token : Group token

    group_type : Group type (Group or Subgroup)

    organization_token : Parent organization token

    subgroups : Subgroup dict containing subgroup name and token

  • Return type: dict

timesys.vigiles.groups.get_group_members(group_token)

Gets a list of group members

  • Parameters: group_token (str) -- Token of the group whose members are to be retrieved
  • Raises: Exception -- If no group_token is provided

  • Returns:

    group_name : Name of the group

    description : Description of the group

    token : Group token

    group_type : Type of the group

    group_members : An array of objects, representing a group member's details

  • Return type: dict

timesys.vigiles.groups.get_group_settings(group_token=None)

Get group settings for a group

If a token is passed, it will be used. If no token is passed, but a group_token is configured on the llapi object, it will be used. If neither are provided, an Exception will be raised.

  • Parameters: group_token (str , optional) -- Token of the group to retrieve group settings info for

  • Returns:

    name : Group name

    token : Group token

    vuln_identifiers: List : List of identifiers used to match the vulnerabilities

    vuln_strict_match: str : "on" if strict vulnerability based on name and vendor is enabled else "off"

  • Return type: dict

timesys.vigiles.groups.get_groups()

Get group info for all groups available to the current user

  • Returns:

    name : Group name

    description : Group description

    token : Group token

    group_type : Group type (Group or Subgroup)

    organization_token : Parent organization token

  • Return type: list of dict containing

timesys.vigiles.groups.remove_group_member(group_token, member_email)

Remove a user from the specified group

  • Parameters:
    • group_token (str) -- Token of the group from which the user is to be removed
    • member_email (str) -- Email Address of the user to be removed from the group

  • Returns:

    message: str : Success message on successfuly adding the user

    status_code: int : Status code

  • Return type: dict

  • Raises: Exception -- If any of the required parameters (group_token, member_email) is not provided.

timesys.vigiles.groups.update_group_member(group_token, member_email, new_role)

Update the group member

  • Parameters:
    • group_token (str) -- Token of the group to which the member is to be updated
    • member_email (str) -- Email address of the member to be updated
    • new_role (str) -- New role to assign to the member

  • Returns:

    message: str : Success message on successfuly adding the user

    status_code: int : Status code

  • Return type: dict

  • Raises: Exception -- If any of the required parameters (group_token, member_email, or role) is not provided.

timesys.vigiles.groups.update_group_settings(group_token=None, vuln_identifiers=None, vuln_strict_match=None)

Update group settings for a group

If a token is passed, it will be used. If no token is passed, but a group_token is configured on the llapi object, it will be used. If neither are provided, an Exception will be raised.

  • Parameters:
    • group_token (str , optional) -- Token of the group to retrieve group settings info for
    • vuln_identifiers (List , Optional) -- List of identifiers used to match the vulnerabilities
    • vuln_strict_match (str , Optional) -- "on" if strict vulnerability based on name and vendor is enabled else "off"

  • Returns:

    message: str : Success message on successfuly updating the group settings

    status_code: int : Status code

  • Return type: dict

timesys.vigiles.folders module

timesys.vigiles.folders.create_folder(folder_name, description=None, group_token=None, folder_token=None)

Create a new folder with given group/folder token

  • Returns: Dictionary of new folder information with keys:

    "folder_name", "group_token", "folder_token", "description", "creation_date"

  • Return type: dict

timesys.vigiles.folders.get_folders(group_token=None, folder_token=None)

Get all folders that are owned by the current user.

If a group token is configured on the llapi object, only folders belonging to that group will be returned.

If a folder token is configured on the llapi object, only folders belonging to that folder will be returned.

  • Returns: List of folder information dictionaries with keys:

    "folder_token", "folder_name", "folder_description", "creation_date", "group_token"

  • Return type: list of dict

timesys.vigiles.reports module

timesys.vigiles.reports.compare_reports(token_one, token_two, remove_whitelist=False, remove_not_affected=False, filter_results=False)

Get comparison between report token_one and report token_two

  • Parameters:
    • token_one (str) -- Token of the first CVE report
    • token_two (str) -- Token of the second CVE report
    • remove_whitelist (bool) -- remove_whitelist is deprecated, use remove_not_affected instead Default: False
    • remove_not_affected (bool) -- Remove Not Affected CVEs from the report if True Default: False
    • filter_results (bool) -- Apply all filters to report if True, else only kernel and uboot config filters if configs have been uploaded. Default: False

  • Returns: Results of comparison with keys:

    resolved : List of CVEs resolved between the reports

    new : List new CVEs between the reports

  • Return type: dict

timesys.vigiles.reports.download_report(report_token, format=None, filter_results=False, cyclonedx_format='json', cyclonedx_version='1.6')

Get a CVE report as a file from the given report token

  • Parameters:
    • token (str) -- The token of the CVE report to download
    • format (str) -- What file format to return from the following: "csv", "pdf", "pdfsummary", "xlsx"
    • filter_results (bool) -- True to apply all configured filters to scan results, False to apply only kernel and uboot config filters, if configs have been uploaded. Default: False
    • cyclonedx_format (str) -- CycloneDX file format to download report in vex format Default: json
    • cyclonedx_version (str) -- CycloneDX spec version to download report in vex format Default: 1.6

  • Returns: file data -- CVE Report data in bytes from the requested file type

  • Return type: bytes