Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs and examples #17

Merged
merged 4 commits into from
Nov 22, 2023
Merged

Improve docs and examples #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8ab0120
improve github workflow example
darrenpmeyer Nov 21, 2023
2aaaf45
improve README to add links to examples
darrenpmeyer Nov 21, 2023
3efa32b
auto-update verdata from pre-push hook
darrenpmeyer Nov 21, 2023
7c12201
README improvements
darrenpmeyer Nov 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .github/workflows/example-use-main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
43 changes: 14 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +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:
## Quick start

- [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
See example [GitHub Action worfklow](.github/workflows/example-use-main.yml) and [GitLab CI config](.gitlab-ci.yml).

## Quick start
**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 git+https://github.com/endorlabs/atst@main`
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
2. In your setup section, install this package with `python3 -m venv ../.atst ; ../.atst/bin/python3 -m pip -q install endorlabs-atst`
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
```

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.
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`

Note that a provided SHA256 hash will always override cached or API-derived values
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.

For example, when downloading version 1.6.8 for macOS on Arm64, one might:

Expand All @@ -31,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
60 changes: 60 additions & 0 deletions endorlabs_atst/utils/verdata.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading