A CLI for the Uleska DevSecOps Platform
Project description
uleska-automate
Uleska CLI for ease of integration with CI/CD and similar systems
___ ___ ___ _______ ________ ___ __ ________
|\ \|\ \|\ \ |\ ___ \ |\ ____\|\ \|\ \ |\ __ \
\ \ \\\ \ \ \ \ \ __/|\ \ \___|\ \ \/ /|\ \ \|\ \
\ \ \\\ \ \ \ \ \ \_|/_\ \_____ \ \ ___ \ \ __ \
\ \ \\\ \ \ \____\ \ \_|\ \|____|\ \ \ \\ \ \ \ \ \ \
\ \_______\ \_______\ \_______\____\_\ \ \__\\ \__\ \__\ \__\
\|_______|\|_______|\|_______|\_________\|__| \|__|\|__|\|__|
\|_________|
usage: uleska-automate [-h] --uleska_host ULESKA_HOST --token TOKEN
[--application_id APPLICATION_ID]
[--version_id VERSION_ID]
[--application_name APPLICATION_NAME]
[--version_name VERSION_NAME]
[--toolkit_name TOOLKIT_NAME] [--update_sast]
[--sast_git SAST_GIT] [--sast_username SAST_USERNAME]
[--sast_token SAST_TOKEN]
[--update_container]
[--container_image CONTAINER_IMAGE]
[--container_tag CONTAINER_TAG]
[--container_connection CONTAINER_CONNECTION] [--test]
[--test_and_results] [--test_and_compare]
[--latest_results] [--compare_latest_results]
[--print_json] [--get_ids] [--app_stats]
[--fail_if_issue_risk_over FAIL_IF_ISSUE_RISK_OVER]
[--fail_if_risk_over FAIL_IF_RISK_OVER]
[--fail_if_risk_change_over FAIL_IF_RISK_CHANGE_OVER]
[--fail_if_issues_over FAIL_IF_ISSUES_OVER]
[--fail_if_issues_change_over FAIL_IF_ISSUES_CHANGE_OVER]
[--fail_if_CVSS_over FAIL_IF_CVSS_OVER] [--debug]
Uleska command line interface. To identify the project/pipeline to test you
can specify either --application_name and --version_name, or --application and
--version (passing GUIDs). Arguments can also be stored in an argparse configuration
file specified with 'uleska-automate @args.txt'. (Version 0.12)
optional arguments:
-h, --help show this help message and exit
--uleska_host ULESKA_HOST
URL to the Uleska host (e.g. https://s1.uleska.com/)
(note final / is required)
--token TOKEN String for the authentication token
--application_id APPLICATION_ID
GUID for the application to reference
--version_id VERSION_ID
GUID for the application version/pipeline to reference
--application_name APPLICATION_NAME
Name for the application to reference
--version_name VERSION_NAME
Name for the version/pipeline to reference
--toolkit_name TOOLKIT_NAME
The name of the toolkit you would like to use to scan.
Note: for backwards compatibility you can call the CLI
without this argument, but this will be depreciated in
the future.
--update_sast Add or update a SAST pipeline. Requires an pre-
existing application. See documentation for other
settings
--sast_git SAST_GIT Git URL for SAST repo. Required with --update_sast.
--sast_username SAST_USERNAME
If repo requires authentication, this is the username
to use. Optional with --update_sast.
--sast_token SAST_TOKEN
If repo requires authentication, this is the token
value to use. Optional with --update_sast.
--update_container Update a container pipeline. Requires an pre-existing
application/config. See documentation for other
settings
--container_image CONTAINER_IMAGE
Name of image to use. Required with
--update_container.
--container_tag CONTAINER_TAG
Tag to use. Required with --update_container.
--container_connection CONTAINER_CONNECTION
Connection name to use for container access. Optional
with --update_container. If not included Docker Hub is
assumed.
--test Run tests only for the application and version
referenced, do not wait for the results
--test_and_results Run tests for the application and version referenced,
and return the results from the last as JSON
--test_and_compare Run tests for the application and version referenced,
and return any differences in the results from the
last test
--latest_results Retrieve the latest test results for application and
version referenced
--compare_latest_results
Retrieve the latest test results for version and
compare
--print_json Print the relevant output as JSON to stdout
--get_ids Retrieve GUID for the application_name and
version_name supplied
--app_stats Retrieve the latest risk and vulnerabiltiy for the
whole application
--fail_if_issue_risk_over FAIL_IF_ISSUE_RISK_OVER
Causes the CLI to return a failure if any new issue
risk is over the integer specified
--fail_if_risk_over FAIL_IF_RISK_OVER
Causes the CLI to return a failure if the risk is over
the integer specified
--fail_if_risk_change_over FAIL_IF_RISK_CHANGE_OVER
Causes the CLI to return a failure if the percentage
change of increased risk is over the integer
specified. Requires 'test_and_compare' or
'compare_latest_results' functions
--fail_if_issues_over FAIL_IF_ISSUES_OVER
Causes the CLI to return a failure if the number of
issues is over the integer specified
--fail_if_issues_change_over FAIL_IF_ISSUES_CHANGE_OVER
Causes the CLI to return a failure if the percentage
change in new issues is over the integer specified.
Requires 'test_and_compare' or
'compare_latest_results' function
--fail_if_CVSS_over FAIL_IF_CVSS_OVER
Causes the CLI to return a failure if the any new
issue has a CVSS over the integer specified. Requires
'test_and_compare' or 'compare_latest_results'
function
--debug Prints debug messages
Example usage:
# python3 uleska-automate.py --uleska_host https://uleska.example.com/ --application_name demo_UnSAFE_Bank --version_name v1 --token c64Ca28whEAIkFYlzO8clRutrlwVws2pF9999999999 --toolkit_name "ABC" --test_and_compare
Application or version name passed, looking up ids...
Application ID found for [demo_UnSAFE_Bank]: 00b17c86-62f8-4031-8fe9-d7ab319a0c3e
Version ID found for [v1]: a2bb3d88-cf9d-496f-9920-bee9122b43a0
Mapped names to ids: application name [demo_UnSAFE_Bank], id [00b17c86-62f8-4031-8fe9-d7ab319a0c3e], version name [v1] id [a2bb3d88-cf9d-496f-9920-bee9122b43a0]
Running blocking scan
Kicking off the scan
Scan running
Our Toolkit a2bb3d88-cf9d-496f-9920-bee9122b43a0 is still running, waiting...
Our Toolkit a2bb3d88-cf9d-496f-9920-bee9122b43a0 is still running, waiting...
Our Toolkit a2bb3d88-cf9d-496f-9920-bee9122b43a0 is still running, waiting...
No more scans running
Getting list of reports for this pipeline
Getting information on this report
Getting information on this report
Comparing the latest scan report with the previous one
Risk level has INCREASED by $215,000
Risk level has INCREASED by 19.9%
Number of issues has INCREASED by 4
Number of issues has INCREASED by 44.4%
NEW ISSUE in this toolkit run:
Using parseString to parse untrusted XML data is known to be vulnerable to XML attacks: reinvent.py: tool [Demo Bandit]: Risk $10,000
CVSS : 6.2 : CVSS:3.0/AV:N/AC:H/PR:H/UI:R/S:C/C:H/I:L/A:N
NEW ISSUE in this toolkit run:
Possible hardcoded password: 'h++jszpm)i@p%ay_b=cp#()^od!qns14)h%@qm3)p=cuo+st^a': tool [Demo Bandit]: Risk $62,000
CVSS : 7.3 : CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:L/A:N
NEW ISSUE in this toolkit run:
Possible hardcoded password: 'secret': tool [Demo Bandit]: Risk $62,000
CVSS : 7.3 : CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:L/A:N
NEW ISSUE in this toolkit run:
HTTP response headers should not be vulnerable to injection attacks: tool [Demo SonarQube]: Risk $81,000
CVSS : 8.2 : CVSS:3.0/AV:N/AC:H/PR:L/UI:N/S:C/C:H/I:H/A:N
New risk in this tookit run = $215,000
Detailed Info on the Paramaters
The Uleska CLI allows you to perform a number of functions as described below. These functions will rely on a combination of parameters being passed.
API Interaction
--uleska_host [hosturl]
REQUIRED. This is the hostname (or hostname and domainname as needed) of the Uleska Platform the CLI script is to invoke the testing or commands on. For example, if you have the Uleska Platform installed at uleska.example.com, you would set this parameter to https://uleska.example.com/ . Note the scheme, and the final forward slash are required.
--token [token]
REQUIRED. Provide the API authentication token retrieved for your chosen user. See the relevant part of the Uleska documentation guide for more information on retrieving auth tokens from the Uleska Platform.
Identifying the Application and Version to be tested
--application_name [name]
The text name of the application descriptor in the Uleska Platform to be tested. This must be an exact string match (case sensitive). Note - if application_name or version_name are supplied to the CLI then any application_id or version_id supplied will be ignored. You must supply a combination of application_name and application_version to identify the testing toolkit and set up to be tested.
--version_name [name]
The text name of the version descriptor in the Uleska Platform to be tested. This must be an exact string match (case sensitive). Note - if application_name or version_name are supplied to the CLI then any applicaiton_id or version_id supplied will be ignored. You must supply a combination of application_name and application_version to identify the testing toolkit and set up to be tested.
--applicaton_id [id]
The GUID associated with the application descriptor in the Uleska Platform. This must be an exact string match. The application ID can be retrieved using the 'get_ids' function of the CLI (see later), or can be viewed in the URL when accessing the application via the Uleska UI (after "/applications/"). Note - if application_name or version_name are supplied to the CLI then any applicaiton_id or version_id supplied will be ignored.
--version_id [id]
The GUID associated with the version descriptor in the Uleska Platform. This must be an exact string match. The version ID can be retrieved using the 'get_ids' function of the CLI (see later), or can be viewed in the URL when accessing the application via the Uleska UI (after "/versions/"). Note - if application_name or version_name are supplied to the CLI then any applicaiton_id or version_id supplied will be ignored.
--toolkit_name [name]
The name of the Toolkit you would like to use in your scan e.g. 'Uleska Code Scan'. This must be an exact string match (case sensitive).
Specifying the type of testing to be conducted
--test
Contacts the Uleska Platform API and invokes the testing toolkit for the application and version specified. Requires a combination of application_name and version_name to be passed, or the application_id and version_id. This starts the testing toolkit only, and returns immediately - i.e. runs in NON-BLOCKING mode. If your pipeline wants to start the testing in one place, and then check the results later, this is the function to use.
--test_and_results
Contacts the Uleska Platform API and invokes the testing toolkit for the application and version specified, runs in BLOCKING mode, waiting for the testing toolkit to complete, when it then retrieves the results. Requires a combination of application_name and version_name to be passed, or the application_id and version_id. This will wait until the toolkit is finished, giving updates as it goes along. When the toolkit has completed, it will retrieve the results of the latest report and display (as text or JSON, depending on the --print_json flag). If your pipeline wants to start the testing and hold for the results of the latest tests to be shown, then use this function. Note that any results returned will not have 'invalid issues' displayed or compared (e.g. issues marked as false positives, duplicates, or non-issues).
--test_and_compare
Contacts the Uleska Platform API and invokes the testing toolkit for the application and version specified, as well as blocking for the testing toolkit to complete, when it then retrieves the latest results and compares those results to the previous results, highlighting any new or fixed issues. Requires a combination of application_name and version_name to be passed, or the application_id and version_id. Runs in BLOCKING mode until the toolkit is finished, giving updates as it goes along. When the toolkit has completed, it will retrieve the results of the latest report, as well as the previous report, and display the differences in risk and issues between those reports (as text or JSON, depending on the --print_json flag). If you want to know 'what's changed' since the last run through the pipeline, this function will highlight new issues found since the last run, as well as issues fixed. It'll also show the differences in numbers of issues and risk. This means you can program automated logic around the testing in your pipeline, e.g. flagging the build or alerting something if the risk or number of issues goes above a specified value, or if issues of type X are found, or based on CVSS, etc. Note that any results returned will not have 'invalid issues' displayed or compared (e.g. issues marked as false positives, duplicates, or non-issues).
--latest_results
Contacts the Uleska Platform API and only retrieves the results of the latest scan for the application and version specified. Requires a combination of application_name and version_name to be passed, or the application_id and version_id. If your pipeline wants to start the testing somewhere else, and come back later for the results, this is the way to get those results in a NON-BLOCKING way. This is the non-blocking equivalent of --test_and_results (only it doesn't kick off the tests). Note that any results returned will not have 'invalid issues' displayed or compared (e.g. issues marked as false positives, duplicates, or non-issues).
--compare_latest_results
Contacts the Uleska Platform API for the latest, and previous results related to the application and version specified, when it then compares those results to the previous results, highlighting any new or fixed issues. Requires a combination of application_name and version_name to be passed, or the application_id and version_id. If your pipeline wants to start the testing somewhere else, and come back later for the results to be compared to see what's changed since the last run, this is the way to get those results in a non-blocking way. This is the non-blocking equivalent of --test_and_compare (only it doesn't kick off the tests). Note that any results returned will not have 'invalid issues' displayed or compared (e.g. issues marked as false positives, duplicates, or non-issues).
--app_stats
Contacts the Uleska Platform API to return high level risk and vulnerability data for the entire application, not just specific versions/stages.
SAST Configuration updates
--update_sast
Flag to tell the CLI to expect configuration updates for SAST parameters, namely the Git Address, Git username, and/or Git auth token. If this flag is set, at least --sast_git must be passed. Note that the CLI SAST config updates can be used to update an existing SAST configuration for a version, it cannot be used to create a new version.
--sast_git [gitaddress]
Used in combination with --update_sast to update the Git Address configuration of the current application and version. Value will be the full Git URL for the relevant codeline to be tested, e.g. "https://github.com/org/mycode.git". This value will overwrite the existing Git Address configured for this version, equivalent to the 'Git Address' input in the UI. Note setting this value automatically marks the 'Source Code Origin' flag to 'Git' for this version.
--sast_username [username]
Used in combination with --update_sast to update the Git Username configuration of the current application and version. Value will be the username required to authenticate to the Git codeline to be tested. This value will overwrite the existing Git Username configured for this version, equivalent to the 'Username' input under 'SCM Authentication' in the UI.
--sast_token [token]
Used in combination with --update_sast to update the Git Password configuration of the current application and version. Value will be the password or auth token required to authenticate to the Git codeline to be tested. This value will overwrite the existing Git Password configured for this version, equivalent to the 'Password' input under 'SCM Authentication' in the UI.
--tools [tools]
Used in combination with --update_sast to update the SAST toolkit of the current application and version. Value will be a comma separated list of security tools configured for your testing. This will overwite the existing toolkit configured. For a list of tools configured for your environment, use the SecureDesigner/api/v1/tools API to list the tools and details (use the 'title' attribute as the tool name). Example usage would be (--tools "Bandit,Dependency Checker,nodejs scan").
Container Configuration updates
--update_container
Flag to tell the CLI to expect configuration updates for container parameters, namely the container image name, container image tag, and possibly the container connection name. If this flag is set, at least --container_image and --container_tag must be passed. Note that the CLI container config updates can be used to update an existing container configuration for a version, it cannot be used to create a new version.
--container_image [name]
Used in combination with --update_container to update the Container Name configuration of the current application and version. This value will overwrite the existing Container Name configured for this version, equivalent to the 'Container Name' input under 'Container' tab in the UI.
--container_tag [tag]
Used in combination with --update_container to update the Container Tag configuration of the current application and version. This value will overwrite the existing Container Tag configured for this version, equivalent to the 'Tag' input under 'Container' tab in the UI.
--container_connection [connection]
Used in combination with --update_container to update the Container Connection configuration of the current application and version. This value will overwrite the existing Container Connection configured for this version, equivalent to the 'Connection' input under 'Container' tab in the UI.
Risk management
--fail_if_issue_risk_over [risk]
Usable with --test_and_results, --test_and_compare, --latest_results, --compare_latest_results. Causes the CLI to return a failure (exit 1) if any individual issue in the results set returned has a risk value setting over the threshold set. In the case of test commands that return the latest set of results (--test_and_results, --latest_results) this will cause a failure exit if any value in the latest result set is over the threshold. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if any value in the new issues found result set is over the threshold.
--fail_if_risk_over [risk]
Usable with --test_and_results, --test_and_compare, --latest_results, --compare_latest_results. Causes the CLI to return a failure (exit 1) if the overall risk returned is over the threshold set. In the case of test commands that return the latest set of results (--test_and_results, --latest_results) this will cause a failure exit if the risk of all issues in the latest result set is over the threshold. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if the combined risk of new issues found result set is over the threshold.
--fail_if_risk_change_over [percentage]
Usable with --test_and_compare, --compare_latest_results. Causes the CLI to return a failure (exit 1) if the overall change in risk returned is over the percentage threshold set. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if the aggregate change in risk of new issues found result set is over the percentage threshold.
--fail_if_issues_over [number]
Usable with --test_and_results, --test_and_compare, --latest_results, --compare_latest_results. Causes the CLI to return a failure (exit 1) if the overall number of issues returned is over the threshold set. In the case of test commands that return the latest set of results (--test_and_results, --latest_results) this will cause a failure exit if the number of all issues in the latest result set is over the threshold. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if the number of new issues found result set is over the threshold.
--fail_if_issues_change_over [percentage]
Usable with --test_and_compare, --compare_latest_results. Causes the CLI to return a failure (exit 1) if the overall change in numbers of issues returned is over the percentage threshold set. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if the aggregate change in numbers of new issues found result set is over the percentage threshold.
--fail_if_CVSS_over [CVSS number]
Usable with --test_and_results, --test_and_compare, --latest_results, --compare_latest_results. Requires an integer number between 0 and 10. Causes the CLI to return a failure (exit 1) if any individual issue in the results set returned has a CVSS value setting over the threshold set. In the case of test commands that return the latest set of results (--test_and_results, --latest_results) this will cause a failure exit if any CVSS value in the latest result set is over the threshold. In the case of test commands that compare the previous sets of results (--test_and_compare, --compare_latest_results) this will cause a failure exit if any CVSS value in the new issues found result set is over the threshold.
Other functions
--print_json
Usable with --test_and_results, --test_and_compare, --latest_results, and --compare_latest_results. Takes the information returned by the Uleska Platform and prints it to stdout in JSON format.
--get_ids
Helper function that takes in the --application_name and --version_name and gives the GUIDs associated with each. Helpful when you don't have access to the UI, or are just to lazy to log in.
--debug
Turns on debugging mode within the CLI script. Nuf said.
For more details on the usage of the Uleska CLI, view the documentation at https://www.uleska.com
Testing
To run tests, please run python3 -m unittest
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for uleska_automate-0.12-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1a06b999f486be86b25245739cd6a6f6725057f5c1294c14e9d16504072274e8 |
|
| MD5 | 3664baff0b0543d919f93529238373d8 |
|
| BLAKE2b-256 | 462769fee255e86f59b2d55e827c5ef9252dfa8bc276f38a13bcf48095d88847 |
