https://github.com/oxsecurity/ox-break-glass
https://github.com/oxsecurity/ox-break-glass
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/oxsecurity/ox-break-glass
- Owner: oxsecurity
- License: apache-2.0
- Created: 2024-07-08T10:46:38.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-12T19:37:04.000Z (almost 2 years ago)
- Last Synced: 2024-12-27T08:30:59.462Z (over 1 year ago)
- Language: TypeScript
- Size: 43.9 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/oxsecurity/ox-break-glass/actions/workflows/ox.yml)
[](https://github.com/oxsecurity/ox-break-glass/actions/workflows/deno.yml)
# ox-break-glass
## Precautions
This is sample code for a one-off tool, not an official product. As such, it is
not supported, though issues will be addressed on a best-effort basis.
## Background and design
To ensure quality and maintain trust, AppDev teams typically agree to safety
procedures established by AppSec representatives. The most powerful of these
blocks a build, with the intent of preventing a disaster (for example,
inadvertent sharing of AWS keys publicly). Yet inevitably, situations arise that
require emergency bypassing of established policies because the importance of
getting a release out takes precedence over the risk to safety. The ability to
bypass OX's safeguards can be controlled by creating an Exclusion.
The requirement is to not force the dev team to login to OX and instead use a
familiar tools, their CI/CD pipeline and Slack, to create a temporary exemption,
which then on a re-run of the build, allows it to proceed. This workflow
delivers that.
## Steps to install the app
1. clone this repo, cd into the ox-break-glass directory
2. make sure you've the necessary permissions by running `slack auth list`
_(reach out to your Slack admin if you don't have the proper permissions)_
3. gather two tokens: an OX API Token from the Ox Dashboard & a Slack OAuth
token with `users.profile:read` Bot Token Scope from a Slack app
4. run `slack install` from within the `ox-break-glass` directory and follow the
prompts
5. run `slack env add OX_API_KEY `
6. run `slack env add SLACK_TOKEN `
7. check that the environment variables were deployed with `slack env list`
8. run `slack deploy` to deploy the application
9. when prompted to `Choose a trigger definition file` accept the listed option
(`triggers/create_exclusion_trigger.ts`)
10. you will then be provided a link to the Workflow which you should then copy
and paste into an appropriately secured channel with only trained,
authorized, and vetted members. The link will looks something like this:
`https://slack.com/shortcuts/Ft07661HPM0U/a30ad178a0227bd7d37c23274cb6a15f`
## Steps to use the workflow
1. create a Slack channel (i.e. Break Glass Workflow)
2. add the workflow link and pin that message to the channel for easy future
access
3. use `Start Workflow` and enter in the "all issues" link from the OX output in
your CI/CD platform
One option for retrieving the input (YAML scans):
Second option (GitHub App):
Third option (GitLab App):
Fourth option (BitBucket App):
4. check the output, which if successful will look something like this:
```
Success! status: 200 response: {"data":{"excludeAlert":{"exclusions":[{"id":"6646e659d706ddad04646729",
"issueName":"K8s container should not be privileged"}]}}}
```
5. check in Ox for a newly created Exclusion. The `excluded by` field should say
`api@ox.security` and the comments will have the Slack user's information. By
default, the Exclusion has a hard coded 3 hour expiration.
6. if instead you see an error, follow the advice from it. Usually errors arise
from malformed or previously used data
Here's a recording demonstrating how to use it:
## Steps to debug
1. use `slack run` to create a locally running instance of the app
2. examine the output in the terminal where you ran `slack run` as you test the
workflow/app
3. add `console.log()` statements as needed to the
`/functions/create_exclusion.ts`
## How the workflow & custom function were built
Follow
[this tutorial](https://api.slack.com/tutorials/tracks/wfb-function#next).
You'll need to deviate slightly from their outdated instructions about custom
inputs and use Forms instead. Add a form from the Steps area and then the rest
should work.
## Steps to uninstall the app
1. from the app's directory, run `slack uninstall`
2. to fully remove, run `slack delete`
You may need to remove the app from both the `Deployed` and `Local` environments
## Historical info
##### _Outdated given added workflow and trigger features but keeping for historical reasons..._
##### _Workflow details_
Here's a screenshot of the workflow's form:
The custom `Create Exclusion` step is the key here that links the workflow to
the code in the `/functions/create_exclusion.ts` file. You'll also need to add
your OX_API_KEY and create a channel to run the workflow within.
##### _Steps to create the workflow_
1. from Slack -> ... More, choose Automations -> Workflow builder -> Create
Workflow
2. start from scratch and select `From a link in Slack`
3. collect info from a form (the All Issues link)
4. use the "Custom Step" to select the `ox-break-glass` app and use the
`Create Exclusion` function from that app
5. add a variable and choose `{} Answer to: What is the All Issues link` for the
input and `Submitting User` as `{} Person who used this workflow`
6. add a send a message step, send it to the channel where the workflow was used
and informative text
7. use the `{} Output` variable to confirm the Exclusion API's output