Code Scanning

This part of the documentation covers all the codescanning APIs.

CodeScanning

class ghastoolkit.CodeScanning(repository: Repository | None = None, retry_count: int = 1, retry_sleep: int | float = 15)

Code Scanning.

__init__(repository: Repository | None = None, retry_count: int = 1, retry_sleep: int | float = 15) → None

Code Scanning REST API.

Retries currently are only for fetching the analyses by default is only done once. If you want to retry more than once you can set the retry_count to a higher number. You can also set the retry_sleep to a higher number to sleep longer between each retry.

https://docs.github.com/en/rest/code-scanning

downloadExtractorPack(repository_name: str, output: str) → str | None

Download Extractor Packs from GitHub Releases.

downloadSARIF(output: str, sarif_id: int) → bool

Get SARIF by ID (UUID).

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#get-a-code-scanning-analysis-for-a-repository

enableDefaultSetup(state: str = 'configured', query_suite: str = 'default', languages: list[str] = []) → dict[str, Any]

Enable Code Scanning using Default Setup using CodeQL.

Permissions: - “Administration” repository permissions (write)

https://docs.github.com/en/rest/code-scanning#set-up-code-scanning

getAlert(alert_number: int) → CodeAlert

Get Single Alert information from Code Scanning.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#get-a-code-scanning-alert

getAlertInstances(alert_number: int, ref: str | None = None) → list[dict]

Get a list of alert instances.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#list-instances-of-a-code-scanning-alert

getAlerts(state: str = 'open', tool_name: str | None = None, ref: str | None = None, sort: str | None = None, severity: str | None = None) → list[CodeAlert]

Get all code scanning alerts.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#list-code-scanning-alerts-for-a-repository

getAlertsInPR(base: str) → list[CodeAlert]

Get the open alerts in a Pull Request (delta / diff).

Note this operation is slow due to it needing to lookup each alert instance information.

Permissions: - “Code scanning alerts” repository permissions (read) - “Pull Requests” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#list-instances-of-a-code-scanning-alert

getAnalyses(reference: str | None = None, tool: str | None = None) → list[CodeScanningAnalysis]

Get a list of all the analyses for a given repository.

This function will retry X times with a Y second sleep between each retry to make sure the analysis is ready. This is primarily used for CodeQL Default Setup in Pull Requests where the analysis might not be ready yet.

Permissions: - “Code scanning alerts” repository permissions (read)

Thrown Exceptions: - GHASToolkitError on retry limit reached - GHASToolkitTypeError on error getting analyses

https://docs.github.com/en/enterprise-cloud@latest/rest/code-scanning#list-code-scanning-analyses-for-a-repository

getCodeQLDatabase(language: str) → dict

Get a CodeQL database for a repository.

Permissions: - “Contents” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#get-a-codeql-database-for-a-repository

getCodeQLDatabases() → list[dict]

List CodeQL databases for a repository.

Permissions: - “Contents” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#list-codeql-databases-for-a-repository

getDefaultConfiguration() → CodeScanningConfiguration

Get Default Code Scanning Configuration.

Permissions: - “Administration” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#get-a-code-scanning-default-setup-configuration–parameters

getFailedAnalyses(reference: str | None = None) → list[CodeScanningAnalysis]

Get Failed Analyses for a given reference. This will return all analyses with errors or warnings.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning

getLatestAnalyses(reference: str | None = None, tool: str | None = None) → list[CodeScanningAnalysis]

Get Latest Analyses for every tool.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#get-a-code-scanning-analysis-for-a-repository

getLatestPackVersion(pack_name: str) → dict

Get the current remote CodeQL pack version.

getOrganizationAlerts(state: str = 'open') → list[CodeAlert]

Get list of Organization Alerts.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning#list-code-scanning-alerts-for-an-organization

getPackVersions(pack_name: str) → list[dict]

Get a list of all remote pack versions.

getPacks(visibility: str = 'internal') → List[dict]

Get all CodeQL Packs from remote GitHub instance.

CodeQL Packs are stored in GitHub’s container registry so this function might return other container images.

getSarifId(url: str) → int

Get the latest SARIF ID from a URL.

getTools(reference: str | None = None) → List[str]

Get list of tools from the latest analyses.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#get-a-code-scanning-analysis-for-a-repository

isCodeQLDefaultSetup() → bool

Check if Code Scanning is using the Default CodeQL Setup.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning

isEnabled() → bool

Check to see if Code Scanning is enabled or not on a repository level.

Permissions: - “Code scanning alerts” repository permissions (read)

https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-analyses-for-a-repository

Code Alert

class ghastoolkit.CodeAlert(number: int, state: str, created_at: str, rule: dict, tool: dict, _instances: list[dict] | None = None)

Code Alert from Code Scanning API.

__str__() → str

To String.

created_at: str

Alert Creation date and time.

property description: str | None

Rule Description / Title.

property instances: list[dict]

Get list of instances of the alert.

number: int

Unique Identifier

rule: dict

Rule Data (rule_id, severity, description, etc).

property rule_id: str

Rule Identifier.

property severity: str

Severity of the alert using security_severity_level.

state: str

State of the alert. States can be open, closed, dismissed, or fixed.

tool: dict

Tool information (name, version, guid).

property tool_fullname: str

Full tool name with version information.

property tool_name: str

Tool name.