From 8ab012078955a47942f1590c017e5bbdc47ce19b Mon Sep 17 00:00:00 2001 From: Darren P Meyer Date: Tue, 21 Nov 2023 09:06:42 -0600 Subject: [PATCH 1/4] improve github workflow example --- .github/workflows/example-use-main.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/example-use-main.yml b/.github/workflows/example-use-main.yml index fdecb1f..6e1161d 100644 --- a/.github/workflows/example-use-main.yml +++ b/.github/workflows/example-use-main.yml @@ -12,10 +12,11 @@ jobs: runs-on: ubuntu-latest env: # DEBUG: 1 + GITHUB_API_URL: "https://api.github.com/" # change for GHES ENDOR_API_CREDENTIALS_KEY: ${{ vars.ENDORLABS_API_KEY }} ENDOR_API_CREDENTIALS_SECRET: ${{ secrets.ENDORLABS_API_SECRET }} ENDOR_NAMESPACE: ${{ vars.ENDORLABS_TENANT_NAME }} - ENDOR_CI_RUN: ${{ github.event_name == 'pull_request' && 'true' || 'false' }} # use CI Run unless this isn't a PR + ENDOR_SCAN_PR: ${{ github.event_name == 'pull_request' && 'true' || 'false' }} # use CI Run unless this isn't a PR steps: - name: Checkout Repository uses: actions/checkout@v3 @@ -25,4 +26,6 @@ jobs: ../.atst/bin/endorlabs-atst setup - name: Endor Labs Scan for ${{ github.event_name }} - run: endorlabs-atst ctl -- scan $CI_RUN + # Running this as a seperate step means the setup environment will be loaded + # Note that most of the config is in job-level env vars + run: endorlabs-atst ctl -- scan From 2aaaf45d3fe1938bd8c5dd1d49c10875b4451fc9 Mon Sep 17 00:00:00 2001 From: Darren P Meyer Date: Tue, 21 Nov 2023 09:08:20 -0600 Subject: [PATCH 2/4] improve README to add links to examples --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 117118f..71962a1 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,10 @@ Examples of how to use this tool are provided in: ## Quick start +See example [GitHub Action worfklow](.github/workflows/example-use-main.yml) and [GitLab CI config](.gitlab-ci.yml). + 1. Make sure you have Python3, PIP, and the venv package installed in your runner -2. In your setup section, install this package with `python3 -m venv ../.atst ; ../.atst/bin/python3 -m pip -q install git+https://github.com/endorlabs/atst@main` +2. In your setup section, install this package with `python3 -m venv ../.atst ; ../.atst/bin/python3 -m pip -q install endorlabs-atst` 3. Ensure your Endor Labs environment is established; setting `ENDOR_NAMESPACE` and any authentication configuration required (in some CI environments, `setup` can do this for you; see "**Automatic CI Setup**" below) 4. Run `../.atst/bin/endorlabs-atst setup` 5. When you've build your project and are ready to test with Endor labs, use `../.atst/bin/endorlabs-atst ctl -- scan` and add any `endorctl` options you require From 3efa32b71715984a0e323c2045c51a7265b84050 Mon Sep 17 00:00:00 2001 From: Darren P Meyer Date: Tue, 21 Nov 2023 09:37:41 -0600 Subject: [PATCH 3/4] auto-update verdata from pre-push hook --- endorlabs_atst/utils/verdata.py | 60 +++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/endorlabs_atst/utils/verdata.py b/endorlabs_atst/utils/verdata.py index 4674e6c..d7ccd66 100644 --- a/endorlabs_atst/utils/verdata.py +++ b/endorlabs_atst/utils/verdata.py @@ -3724,6 +3724,66 @@ 'os': 'windows', 'sha256': 'f9442c3f6be7a8f8e9f159957ffd0c475c61b20eb832f86d2646d8268a7f257e', 'version': '1.6.54'}, + '1.6.55_linux_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.55_linux_amd64', + 'os': 'linux', + 'sha256': '60c81cfcfeeaaac0fcc707f3322fc96da98f2475b9cd2d0b8e9cc53e0692d489', + 'version': '1.6.55'}, + '1.6.55_macos_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.55_macos_amd64', + 'os': 'macos', + 'sha256': 'de14032bc8e4ca4b77e2571ecd6562d65df20f9d1c93cd5b4cb42075cb204829', + 'version': '1.6.55'}, + '1.6.55_macos_arm64': {'arch': 'arm64', + 'name': 'endorctl_v1.6.55_macos_arm64', + 'os': 'macos', + 'sha256': 'e7b72c5057c1b5ee542a7f1067f41f13ceab476a69c254afbc0f7c7e1bc56d7a', + 'version': '1.6.55'}, + '1.6.55_windows_amd64.exe': {'arch': 'amd64', + 'name': 'endorctl_v1.6.55_windows_amd64.exe', + 'os': 'windows', + 'sha256': 'f71714948481047c7388aa90760bf3e7cee586ecfcc35bf627af4458ef733e7a', + 'version': '1.6.55'}, + '1.6.56_linux_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.56_linux_amd64', + 'os': 'linux', + 'sha256': 'c147d51eb4834eff265c1ea5854ebdbf9be015d8161a91e6aa537fa729b48a2f', + 'version': '1.6.56'}, + '1.6.56_macos_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.56_macos_amd64', + 'os': 'macos', + 'sha256': '6abc0038d50b8fc27b8800683aa73e94690a06ff28d63c365d815dc90b455202', + 'version': '1.6.56'}, + '1.6.56_macos_arm64': {'arch': 'arm64', + 'name': 'endorctl_v1.6.56_macos_arm64', + 'os': 'macos', + 'sha256': '8397b6ea72c89c1c4a13089b4f6ac39fb5377af78f51ec0a870ad44faae0bf4a', + 'version': '1.6.56'}, + '1.6.56_windows_amd64.exe': {'arch': 'amd64', + 'name': 'endorctl_v1.6.56_windows_amd64.exe', + 'os': 'windows', + 'sha256': 'ed3d528da2ec0008a8f91a02052b8eedd38e94d5bc9e67a359021081b44f2107', + 'version': '1.6.56'}, + '1.6.57_linux_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.57_linux_amd64', + 'os': 'linux', + 'sha256': 'd8ede320494186eca19eb0dcec948188f34b15e8ce7108e3b0fc58433320a82a', + 'version': '1.6.57'}, + '1.6.57_macos_amd64': {'arch': 'amd64', + 'name': 'endorctl_v1.6.57_macos_amd64', + 'os': 'macos', + 'sha256': '0c45d091135d06b18ef40c0693ce96750f144b8e2ceca26e0ec4f4fdbd453baa', + 'version': '1.6.57'}, + '1.6.57_macos_arm64': {'arch': 'arm64', + 'name': 'endorctl_v1.6.57_macos_arm64', + 'os': 'macos', + 'sha256': 'deacfa54161f473552cd8a578f63e3152b199d2702d212823017d18ed73836da', + 'version': '1.6.57'}, + '1.6.57_windows_amd64.exe': {'arch': 'amd64', + 'name': 'endorctl_v1.6.57_windows_amd64.exe', + 'os': 'windows', + 'sha256': '339b41aa8f2f294c19578feac68f934f9838d02a1a02b1a5bb0304a53d919a1a', + 'version': '1.6.57'}, '1.6.5_linux_amd64': {'arch': 'amd64', 'name': 'endorctl_v1.6.5_linux_amd64', 'os': 'linux', From 7c1220102b9771e34248647598c3ff54ff9ec7e6 Mon Sep 17 00:00:00 2001 From: Darren P Meyer Date: Tue, 21 Nov 2023 09:38:24 -0600 Subject: [PATCH 4/4] README improvements --- README.md | 41 ++++++++++++----------------------------- 1 file changed, 12 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 71962a1..2a2a418 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,31 @@ # endorlabs-atst A Python-based tool to help deploy, run, and manage Endor Labs in your CI pipeline -Examples of how to use this tool are provided in: - -- [example-use-main.yml](.github/workflows/example-use-main.yml) -- GitHub Actions workflow example (note: you probably would be better off with the [Endor Labs GitHub Action](https://github.com/marketplace/actions/endor-labs-scan)) -- [.gitlab-ci.yml](.gitlab-ci.yml) -- GitLab CI example - ## Quick start See example [GitHub Action worfklow](.github/workflows/example-use-main.yml) and [GitLab CI config](.gitlab-ci.yml). +**Note:** if using GitHub Actions, you're probably better off with the [Endor Labs GitHub Action](https://github.com/marketplace/actions/endor-labs-scan)) instead + 1. Make sure you have Python3, PIP, and the venv package installed in your runner 2. In your setup section, install this package with `python3 -m venv ../.atst ; ../.atst/bin/python3 -m pip -q install endorlabs-atst` -3. Ensure your Endor Labs environment is established; setting `ENDOR_NAMESPACE` and any authentication configuration required (in some CI environments, `setup` can do this for you; see "**Automatic CI Setup**" below) -4. Run `../.atst/bin/endorlabs-atst setup` -5. When you've build your project and are ready to test with Endor labs, use `../.atst/bin/endorlabs-atst ctl -- scan` and add any `endorctl` options you require +3. Configure your environment for an Endor Labs scan -- see [Endor Labs scan flags and variables documentation](https://docs.api.endorlabs.com/endorctl/environment-variables/#endorctl-scan-flags-and-variables) +4. When you've build your project and are ready to test with Endor labs, use `../.atst/bin/endorlabs-atst ctl -- scan` and add any `endorctl` options you require -- note the freestanding `--`; this separates options for ATST from options for `endorctl` Remember to configure your scan environment variables and authentication as [the Endor Labs Documentation](https://docs.api.endorlabs.com) explains. ## Pinning and verifying endorctl versions -`endorlabs-atst setup` by default installs the latest version (unless there's already an `endorctl` of the current minor version installed) and verifies it using the SHA256 data provided by the Endor Labs API. However, you can pin a particular version of endorctl as well by providing the option `--endorlabs-version` +``` +endorlabs-atst setup --endorlabs-version VERSION [--endorlabs-sha256sum SHA256_SUM] +endorlabs-atst ctl -- scan +``` + +AT-ST by default installs the latest version (unless there's already an `endorctl` of the current minor version installed) and verifies it using the SHA256 data provided by the Endor Labs API. However, you can pin a particular version of endorctl as well by running the `setup` subcommand and providing the option `--endorlabs-version` -When specifying a version, you also have the option of specifying a SHA256 hash of the binary you expect for your OS and architecture (using `--endorlabs-sah256sum` option), so that ATST can verify the download. If you do not provide this, ATST will attempt to look one up from its cache of known versions; however, this cache is only updated when ATST is changed, so recent versions may not exist. +When specifying a pinned version, the SHA256 digest used for verification is loaded from this module rather than the API. Because this internal database is only updated when AT-ST is updated, recent version digests may not be available. You have the option of specifying the SHA256 digest to use (using `--endorlabs-sah256sum` option) yourself -- if no digest is available, verification will be skipped with a warning. -Note that a provided SHA256 hash will always override cached or API-derived values +Note that a provided SHA256 hash will always override cached or API-derived values. For example, when downloading version 1.6.8 for macOS on Arm64, one might: @@ -33,21 +34,3 @@ endorlabs-atst setup --endorlabs-version 1.6.8 --endorlabs-sha256sum e4ffa898606 ``` In all cases, if there is no SHA256 data available, ATST will warn you of this and proceed; while if SHA256 data is available and does not match the `endorctl` that ATST downloads, ATST will terminate with an error. - -## Automatic CI setup - -***NB:*** *currently only available in GitHub Actions CI workflow environments* - -For supported CI systems, you don't need to pre-set your Endor Labs environment variables for auth and namespace before running `endorlabs-atst`, so long as you provide the data as command-line options when you run `endorlabs-atst setup`: - -```bash -../.atst/bin/endorlabs-atst setup --namespace MY_NAMESPACE --auth api:API_KEY:API_SECRET --endorlabs-version latest -``` - -Will (for GitHub only, currently): - -1. set the `PATH` to include `../.atst/bin`, so you can run future ATST or `endorctl` invocations without a full path -2. set the `ENDOR_NAMESPACE` environment variable -3. set the appropriate Endor Labs authentication environment variables - -This is designe to make testing and setup faster, however for production deployments we recommend configuring environment variables and secrets using your CI configuration system -- it's more maintainable