Where should allowed-endpoints be stored?

[varunsh-coder]

If you have used harden-runner, you know that you first start in audit mode.

steps:
  - uses: step-security/harden-runner@14dc64f30986eaa2ad2dddcec073f5aab18e5a24 # v1
    with:
      egress-policy: audit

You then get a link to the insights and recommended policy. As of now, you can take the list of allowed-endpoints and add them to the GitHub Actions workflow file.

Some developers have expressed desire to not store the endpoints in the workflow file. This is to not have to update the workflow periodically in case the endpoints change. Although the endpoints should not change often, I would like to understand if allowed-endpoints should be stored in the backend.

Backend is the API and data store that stores the correlated outbound traffic.
e.g. when you visit https://app.stepsecurity.io/github/jauderho/dockerfiles/actions/runs/1742888941, it fetches the data for that workflow run and shows it from the backend API.

Now, the idea is that instead of adding the allowed-endpoints in the workflow YAML file, you can simply check the endpoints that should be allowed, and save the policy using the insights page using a save policy button. Then the policy will get saved along with the insights in the backend. Next time the same workflow runs, harden-runner will fetch the policy from the backend and then block traffic based on that policy. This way, if there is a new endpoint, one does not need to change the workflow YAML file (so no need to do pull request and update the YAML file). Just go to the insights page, and approve the new endpoint.

The downside is that the allowed-endpoints are not visible in the YAML file.

What are your thoughts? Should the option to store allowed-endpoints in the backend be enabled?

[wallies]

@varunsh-coder i think in the workflow file or in the backend API is fine. Im looking at saving them in environment variables, so i can declare them easier for the entire organisation.

[varunsh-coder]

@wallies by saving them in env variables, you mean as GitHub Action secret at organization level? If so, that is an interesting idea.

I did envision setting allowed-endpoints at an org level, potentially with different lists, e.g. one for publishing workflows, one for CI workflows etc. In the insights page there could be a self-service workflow for a developer to add a new endpoint to a pre-defined list for the org.

Do let me know if you have any issues with saving them in env variables or if you prefer an experience on the backend API/ insights website for this. Thanks!

[ericcornelissen]

@varunsh-coder another alternative over storing the config in the workflow is to store it in a separate file. For example, a file called .github/harden-runner.yml (file may be configurable) which, for now, would have the contents:

allowed-endpoints: >
  aa
  bb
  cc

Two existing Actions that take this approach are actions/labeler (with .github/labeler.yml) and codecov/codecov-action (with .github/codecov.yml).

The advantage of this over having the configuration in the workflow file is that you don't need to change the workflow file to change the configuration. Additionally, a separate configuration file will be cleaner when there are more configuration fields available - it would even be a necessity if more complex configuration (with nested objects) are required (since with: is only allowed to be a "flat" object).

The advantage of this over storing it on the BE is that it is still version controlled by the developers.

One disadvantage, I guess, is how to deal with different jobs having different allow lists. One solution could be to separate configurations by their job key, e.g.:

# .github/workflows/example.yml

jobs:
  example:
    name: Example
    runs-on: ubuntu-latest
    steps:
      - name: Harden runner
        uses: step-security/[email protected]
        with:
          egress-policy: block


# .github/harder-runner.yml

example: # <-- matches the key of the job in the workflow.
  allowed-endpoints: >
    aa
    bb
    cc

[varunsh-coder]

Thanks for sharing the idea @ericcornelissen! Definitely looks promising. Some things to consider:

1. The .github/harder-runner.yml file will need to have configuration for all the jobs and all the workflows. So, there should be a way to specify different workflow files as well. The advantage is that one could specify base configuration across workflows, since lot of endpoints are common, and then have a way to specify additional ones.
2. One challenge developers face today is to copy allowed endpoints from the insights website and paste it back in the workflow. There is an open issue to automatically add allowed endpoints in the workflow file in the insights website, but this requires having access to the workflow file in the back end, which is not the case right now. This config option could solve it, as I believe GitHub allows getting access to a single file to a GitHub app.
3. One would have to consider backward compatibility as well, as some developers might want to specify allowed endpoints in the workflow. So how should the developer know whether they are in the workflow file or in the config. I guess some sort of order of evaluation will need to be defined.

[ericcornelissen]

The .github/harder-runner.yml file will need to have configuration for all the jobs and all the workflows. So, there should be a way to specify different workflow files as well.

Indeed. I listed one possibility for that in the original comment (have a key in the config file that matches the key of the job in the workflow file). Another option I thought of after writing my comment is to have an option in the workflow file that points to an object in the configuration file. This would also allow for re-use of a configuration across multiple jobs.

# .github/workflows/example.yml
jobs:
  example:
    name: Example
    runs-on: ubuntu-latest
    steps:
      - name: Harden runner
        uses: step-security/[email protected]
        with:
          egress-policy: block
          config-key: my-config


# .github/harder-runner.yml
my-config: # <-- matches the `config-key`specified in the workflow.
  allowed-endpoints: >
    aa
    bb
    cc

One would have to consider backward compatibility as well, as some developers might want to specify allowed endpoints in the workflow. So how should the developer know whether they are in the workflow file or in the config. I guess some sort of order of evaluation will need to be defined.

Yes, I think defining some order of evaluation is the way to go (initially¹). But, I think that would also be the case with a BE configuration solution, or any other solution for that matter.

Footnotes

1. I would personally drop the in-workflow configuration with a major version bump at some point. ↩

[varunsh-coder]

The .github/harder-runner.yml file will need to have configuration for all the jobs and all the workflows. So, there should be a way to specify different workflow files as well.

Indeed. I listed one possibility for that in the original comment (have a key in the config file that matches the key of the job in the workflow file). Another option I thought of after writing my comment is to have an option in the workflow file that points to an object in the configuration file. This would also allow for re-use of a configuration across multiple jobs.

# .github/workflows/example.yml
jobs:
  example:
    name: Example
    runs-on: ubuntu-latest
    steps:
      - name: Harden runner
        uses: step-security/[email protected]
        with:
          egress-policy: block
          config-key: my-config


# .github/harder-runner.yml
my-config: # <-- matches the `config-key`specified in the workflow.
  allowed-endpoints: >
    aa
    bb
    cc

One would have to consider backward compatibility as well, as some developers might want to specify allowed endpoints in the workflow. So how should the developer know whether they are in the workflow file or in the config. I guess some sort of order of evaluation will need to be defined.

Yes, I think defining some order of evaluation is the way to go (initially1). But, I think that would also be the case with a BE configuration solution, or any other solution for that matter.

Footnotes

1. I would personally drop the in-workflow configuration with a major version bump at some point. ↩

I like the config-key idea. I am not sure about dropping the in-workflow config as that is much easier to do for simpler/ smaller workflows, and to help developers get started.

[christophetd]

As a first step, how about extracting the list to an external file? It should be relatively easy to implement while allowing to share allowed endpoints between workflows or not.

Example:

jobs:
  unit-test:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@2e205a28d0e1da00c5f53b161f4067b052c61f34
        with:
          egress-policy: block
          allowed-endpoints-file: .github/allowed-ci-endpoints.txt

[varunsh-coder]

Thanks for the feedback! Yes, other users have also shared similar feedback. I will prioritize this. There are a few other settings as well, e.g. related to detecting source code overwrite, that need to go into a config file. Will come up with a draft plan and share in this discussion.