{"id":18635129,"url":"https://github.com/oxsecurity/ox-break-glass","last_synced_at":"2025-11-04T12:30:21.217Z","repository":{"id":247997451,"uuid":"825704697","full_name":"oxsecurity/ox-break-glass","owner":"oxsecurity","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-12T19:37:04.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-27T08:30:59.462Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-08T10:46:38.000Z","updated_at":"2024-08-12T19:37:07.000Z","dependencies_parsed_at":"2024-07-24T18:45:14.015Z","dependency_job_id":"15d57c88-1019-484b-999c-d0f917bc1709","html_url":"https://github.com/oxsecurity/ox-break-glass","commit_stats":null,"previous_names":["oxsecurity/ox-break-glass"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxsecurity%2Fox-break-glass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxsecurity%2Fox-break-glass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxsecurity%2Fox-break-glass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxsecurity%2Fox-break-glass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxsecurity","download_url":"https://codeload.github.com/oxsecurity/ox-break-glass/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239433909,"owners_count":19637806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T05:23:34.981Z","updated_at":"2025-11-04T12:30:21.180Z","avatar_url":"https://github.com/oxsecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![OX Security Scan](https://github.com/oxsecurity/ox-break-glass/actions/workflows/ox.yml/badge.svg)](https://github.com/oxsecurity/ox-break-glass/actions/workflows/ox.yml)\n[![Deno Linter](https://github.com/oxsecurity/ox-break-glass/actions/workflows/deno.yml/badge.svg)](https://github.com/oxsecurity/ox-break-glass/actions/workflows/deno.yml)\n\n# ox-break-glass\n\n## Precautions\n\nThis is sample code for a one-off tool, not an official product. As such, it is\nnot supported, though issues will be addressed on a best-effort basis.\n\n## Background and design\n\nTo ensure quality and maintain trust, AppDev teams typically agree to safety\nprocedures established by AppSec representatives. The most powerful of these\nblocks a build, with the intent of preventing a disaster (for example,\ninadvertent sharing of AWS keys publicly). Yet inevitably, situations arise that\nrequire emergency bypassing of established policies because the importance of\ngetting a release out takes precedence over the risk to safety. The ability to\nbypass OX's safeguards can be controlled by creating an Exclusion.\n\nThe requirement is to not force the dev team to login to OX and instead use a\nfamiliar tools, their CI/CD pipeline and Slack, to create a temporary exemption,\nwhich then on a re-run of the build, allows it to proceed. This workflow\ndelivers that.\n\n## Steps to install the app\n\n1. clone this repo, cd into the ox-break-glass directory\n2. make sure you've the necessary permissions by running `slack auth list`\n   _(reach out to your Slack admin if you don't have the proper permissions)_\n3. gather two tokens: an OX API Token from the Ox Dashboard \u0026 a Slack OAuth\n   token with `users.profile:read` Bot Token Scope from a Slack app\n4. run `slack install` from within the `ox-break-glass` directory and follow the\n   prompts\n5. run `slack env add OX_API_KEY \u003cyour_api_key_here\u003e`\n6. run `slack env add SLACK_TOKEN \u003cyour_slack_xoxb*_token_here\u003e`\n7. check that the environment variables were deployed with `slack env list`\n8. run `slack deploy` to deploy the application\n9. when prompted to `Choose a trigger definition file` accept the listed option\n   (`triggers/create_exclusion_trigger.ts`)\n10. you will then be provided a link to the Workflow which you should then copy\n    and paste into an appropriately secured channel with only trained,\n    authorized, and vetted members. The link will looks something like this:\n    `https://slack.com/shortcuts/Ft07661HPM0U/a30ad178a0227bd7d37c23274cb6a15f`\n\n## Steps to use the workflow\n\n1. create a Slack channel (i.e. Break Glass Workflow)\n2. add the workflow link and pin that message to the channel for easy future\n   access\n3. use `Start Workflow` and enter in the \"all issues\" link from the OX output in\n   your CI/CD platform\n\nOne option for retrieving the input (YAML scans):\u003cbr\u003e\n\u003cimg width=\"700\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/93d2746d-6eec-4eba-bdf0-c6ffd5373fc2\"\u003e\u003cbr\u003e\nSecond option (GitHub App):\u003cbr\u003e\n\u003cimg width=\"700\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/da335adf-659b-41d4-bc95-ff7295447210\"\u003e\u003cbr\u003e\nThird option (GitLab App):\u003cbr\u003e\n\u003cimg width=\"325\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/a4eb1dcd-7aaf-4f9c-9dbf-95b0c6acfd5e\"\u003e\u003cbr\u003e\nFourth option (BitBucket App):\u003cbr\u003e\n\u003cimg width=\"200\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/a410b861-1e4f-4936-8235-04ba5071cb4c\"\u003e\n\n4. check the output, which if successful will look something like this:\n   ```\n   Success! status: 200 response: {\"data\":{\"excludeAlert\":{\"exclusions\":[{\"id\":\"6646e659d706ddad04646729\",\n   \"issueName\":\"K8s container should not be privileged\"}]}}}\n   ```\n5. check in Ox for a newly created Exclusion. The `excluded by` field should say\n   `api@ox.security` and the comments will have the Slack user's information. By\n   default, the Exclusion has a hard coded 3 hour expiration.\n6. if instead you see an error, follow the advice from it. Usually errors arise\n   from malformed or previously used data\n\nHere's a recording demonstrating how to use it:\n![using-ox-break-glass](https://github.com/aaronhmiller/ox-break-glass/assets/223486/1a09480d-23d4-47fe-a405-d43afc2bdd0e)\n\n## Steps to debug\n\n1. use `slack run` to create a locally running instance of the app\n2. examine the output in the terminal where you ran `slack run` as you test the\n   workflow/app\n3. add `console.log()` statements as needed to the\n   `/functions/create_exclusion.ts`\n\n## How the workflow \u0026 custom function were built\n\nFollow\n[this tutorial](https://api.slack.com/tutorials/tracks/wfb-function#next).\nYou'll need to deviate slightly from their outdated instructions about custom\ninputs and use Forms instead. Add a form from the Steps area and then the rest\nshould work.\n\n## Steps to uninstall the app\n\n1. from the app's directory, run `slack uninstall`\n2. to fully remove, run `slack delete`\n\nYou may need to remove the app from both the `Deployed` and `Local` environments\n\n## Historical info\n\n##### _Outdated given added workflow and trigger features but keeping for historical reasons..._\n\n##### _Workflow details_\n\nHere's a screenshot of the workflow's form: \u003cbr\u003e\n\u003cimg width=\"400\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/b5ca8ee4-3b4e-420d-9d9c-1792683564e1\"\u003e\n\nThe custom `Create Exclusion` step is the key here that links the workflow to\nthe code in the `/functions/create_exclusion.ts` file. You'll also need to add\nyour OX_API_KEY and create a channel to run the workflow within.\n\n##### _Steps to create the workflow_\n\n1. from Slack -\u003e ... More, choose Automations -\u003e Workflow builder -\u003e Create\n   Workflow\n2. start from scratch and select `From a link in Slack`\n3. collect info from a form (the All Issues link)\n4. use the \"Custom Step\" to select the `ox-break-glass` app and use the\n   `Create Exclusion` function from that app\n5. add a variable and choose `{} Answer to: What is the All Issues link` for the\n   input and `Submitting User` as `{} Person who used this workflow` \u003cbr\u003e\n   \u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/aaronhmiller/ox-break-glass/assets/223486/fc68ae09-c14b-4055-bf31-4e8729c1262b\"\u003e\n6. add a send a message step, send it to the channel where the workflow was used\n   and informative text\n7. use the `{} Output` variable to confirm the Exclusion API's output\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxsecurity%2Fox-break-glass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxsecurity%2Fox-break-glass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxsecurity%2Fox-break-glass/lists"}