--- description: "Installation of the Fluid Attacks CI Gate, an automated measure to secure your software development lifecycle." keywords: "Fluid Attacks platform, CI Gate, CI/CD, Break the build, Vulnerability remediation, Installation, DevSecOps, Fluid Attacks documentation " other: private: false title: Install CI Gate to break the build --- # Install CI Gate to break the build import { Image } from "@/components/image"; > [!NOTE] > > **Alert:** The Docker tag `new` for the CI Gate image was **removed** on 11/07/2024. If you currently use this tag, please switch for `latest` to preserve support and avoid disruption. You can use Fluid Attacks' CI Gate on any [x86_64](https://en.wikipedia.org/wiki/X86-64) or aarch64 machine in which [Docker](https://help.fluidattacks.com/portal/en/kb/articles/stack-docker) is installed. Access to Internet is required, as CI Gate must connect to the API. You can also integrate this security gate into your CI/CD to ensure your software is built and shipped without vulnerabilities previously reported via Fluid Attacks' platform. In order to use the CI Gate, there are some requirements: 1. Make sure you have a **CI Gate token**. This token [can be generated](https://help.fluidattacks.com/portal/en/kb/articles/prevent-the-deployment-of-builds-with-vulnerabilities#Generate_the_DevSecOps_token) in the platform's **Scope** section (**Organization > Groups > GroupName > Scope**), where you will find the **CI Gate** card. Find the CI Gate token management option on the Fluid Attacks platform

Find the CI Gate token management option on the Fluid Attacks platform

1. Click on the **Manage** **token** button, and a pop-up window will appear where you can generate the token. If you have already generated one, click on **Reveal token**. Generate the CI Gate token on the Fluid Attacks platform

Generate the CI Gate token on the Fluid Attacks platform

> [!TIP] > > **Note:** The CI Gate token is valid for **180 days**, and each token is unique and different for each group. Also, keep in mind that the generation/renewal of the gate token is the users' work. The roles that can generate this token are [User](https://help.fluidattacks.com/portal/en/kb/articles/understand-roles#User_role), [Group Manager](https://help.fluidattacks.com/portal/en/kb/articles/understand-roles#Group_Manager_role) and [Vulnerability Manager](https://help.fluidattacks.com/portal/en/kb/articles/understand-roles#Vulnerability_Manager_role). If you want to run the CI Gate on your local machine: 1. Make sure your execution environment has the required dependencies: Docker (>= 20.10.10). 1. Install Docker by following [the official guide](https://docs.docker.com/engine/install/). > [!TIP] > > **Note:** You can also run CI Gate in one of your CI/CD pipelines on a third-party repository, such as GitHub, GitLab, Azure, and others, without installing Docker on your machine or premises. > [!TIP] > > See the general [resource requirements for the CI Gate](https://help.fluidattacks.com/portal/en/kb/articles/local-tools). ## Arguments > [!NOTE] > > [Since April 4](https://news.fluidattacks.tech/whats-new-with-fluid-attacks-4j91eM), the argument `--cvss` is unavailable. This argument allowed you to choose using the CVSS v3.1 with CI Gate, but now only v4.0 is supported. You can customize the CI Gate's behavior according to your necessities, whether in your local machine or your CI/CD pipeline. The arguments are the following: ### Required `--token`: your CI Gate token. ### Optional - `--breaking`: strict mode severity customization. Vulnerable locations with a severity below this threshold will not break the pipeline. This option takes values from 0.0 (recommended) to 10.0. - If used, and the associated policy in the Fluid Attacks platform is configured, the lowest of the two values is used. - If not used, and the associated policy in the Fluid Attacks platform is configured, the value set in the policy will be used. - If not used, and the associated policy in the Fluid Attacks platform is not configured, the default value is 0.0. - `--dynamic`: retrieves only DAST vulnerabilities from the Fluid Attacks' platform. If not used, all types of vulnerabilities will be retrieved. - `--feature-preview`: enables the feature preview mode. This mode controls from which data source the vulnerability information will be extracted: - `False` uses a resolver that relies on OpenSearch. - `True` uses a resolver that relies on DynamoDB. Defaults to `False`. - `--inherited`: indicates the vulnerabilities detected with [SCA](https://help.fluidattacks.com/portal/en/kb/articles/what-is-sca) that the CI Gate must ignore when instructed to break the build: - `all`: CI Gate ignores all vulnerabilities detected with SCA. - `build`: CI Gate ignores the vulnerabilities in third-party components your software depends on only in the development stage. - `run`: CI Gate ignores the vulnerabilities in third-party components your software depends on in the production stage. - `--repo-name`: Git repository nickname in the Fluid Attacks' platform. If used, only the vulnerabilities from this repository are retrieved. - `--repo-path`: Path to check for in the report. Static vulnerabilities matching these will be included, with the rest being discarded. Globs are allowed within quotation marks, e.g., `path/to/product` or `"path/to/other/product/**"` or `"**/*.py"`. Multiple paths can be provided to CI Gate by repeating `--repo-path`, e.g., `--repo-path path1 --repo-path path2 --repo-path "path3/*"` and so on. > [!CAUTION] > > **Warning:** CI Gate does not validate if these paths actually exist in the repository. Make sure to check them and update them regularly if the repo structure changes. - `-O / --output`: If used, this option saves the execution's output in JSON format to the file specified. - `-p / --proxy`: Sets the address of the HTTP proxy that will be used during the requests. Defaults to `""`. - `--static`: Retrieves only vulnerabilities of type LINES. These are related to source code and include the following techniques: SCR, SAST, and SCA. If not used, all types of vulnerabilities will be retrieved. - `--strict/--lax`: Enables/Disables strict mode, which breaks the build if there are open or untreated vulnerabilities. Default to `--lax`. - `--verbose`: Sets the level of detail of the report. - `-v`: Shows non-compliant, vulnerable locations that would break policy[1](https://help.fluidattacks.com/portal/en/kb/articles/install-the-ci-agent-to-break-the-build#Footnotes),[2](https://help.fluidattacks.com/portal/en/kb/articles/install-the-ci-agent-to-break-the-build#Footnotes), and thus, the build in strict mode. - `-vv`: Shows vulnerable locations regardless of policy compliance. Defaults to `-vv`. - `--verify-proxy-ssl/--no-verify-proxy-ssl`: Enables/Disables SSL certificate validation when requests are sent through an HTTP proxy. This is useful if the proxy uses self-signed certificates. Defaults to `--verify-proxy-ssl`. > [!TIP] > > **Note:** Strict mode customization, such as severity thresholds and grace periods for new locations, can also be set in your organization's **Policies** tab in the platform. In the case of `--breaking`, the value set in the platform, if set, caps the value passed to this CLI option. Furthermore, if you do not define the "breaking" argument, CI Gate will consider the value specified in the policies when determining whether to break the build. For example, suppose you do apply the `--breaking` argument; in that case, the gate will consider the lower severity value between the one specified in the policy and the one you defined in the argument. > [!TIP] > > **Tip:** You can check the CI Gate arguments in your container by running the following command: > `docker run --rm -ti fluidattacks/forces:latest forces --help` ## Run CI Gate on your local machine Here, you will find examples of running CI Gate on a local machine. Remember that you can use different arguments according to the need or context to visualize the execution. Once Docker is successfully installed on your local machine, run the **Docker image**, which will help you download all of CI Gate's dependencies through this command: ``` docker pull fluidattacks/forces:latest ``` To run the container, here are some examples: - To check `all` findings, including static and dynamic: ``` docker run --rm -ti fluidattacks/forces:latest forces --token -vv ``` - To check `static` locations only: ``` docker run --rm -ti fluidattacks/forces:latest forces --static --strict --token ``` - To check `dynamic` locations only: ``` docker run --rm -ti fluidattacks/forces:latest forces --dynamic --strict --token ``` - To verify the locations of a specific repository: ``` docker run --rm -ti fluidattacks/forces:latest forces --dynamic --strict --repo-name --token ``` - To break the pipeline only if vulnerable vulnerabilities with a severity equal to or greater than 4.5 are found: ``` docker run --rm -ti fluidattacks/forces:latest forces --dynamic --strict --breaking 4.5 --token ``` > [!NOTE] > > **Tip:** The `--rm` and `--ti` parameters are optional. Thus, you can define the best way according to your context. You can also run CI Gate on your local machine using Fluid Attacks' [Makes](https://makes.fluidattacks.tech/) framework. Just follow the [installation procedure](https://makes.fluidattacks.tech/getting-started/) and run CI Gate with this command: ``` m gitlab:fluidattacks/universe@trunk /forces --token ``` Plus, any other arguments you wish. The arguments and expected behavior are the same as you would get running the Docker image. You can visualize the report in your terminal and the **DevSecOps** table. As mentioned above, to see the available arguments, just run this command: ``` m gitlab:fluidattacks/universe@trunk /forces --help ``` ## Run CI Gate on your CI/CD If you want to run CI Gate from your repository's pipeline, the following are some examples. ### Bitbucket Pipelines On **Bitbucket Pipelines**, add these lines to your configuration file: ``` # bitbucket-pipelines.yml ``` ``` pipelines: ``` ``` default: ``` ``` - step: ``` ``` name: Fluid-Attacks-CI-Gate ``` ``` services: - docker script: ``` ``` - docker pull fluidattacks/forces:latest - docker run fluidattacks/forces:latest forces --token ``` ### GitLab On **GitLab**, add these lines to your `.gitlab-ci.yml`: ``` forces: image: name: fluidattacks/forces:latest script: - forces --token --strict --repo-name ``` ### Azure DevOps On **Azure DevOps**, add these lines to your configuration file: ``` jobs: - job: Fluidattacks Agent pool: vmImage: "ubuntu-latest" steps: - script: | docker pull fluidattacks/forces:latest \ && docker run fluidattacks/forces:latest forces --token ``` ### Jenkins On **Jenkins**, the configuration file should look like this: ``` pipeline { agent { label 'label' } environment { TOKEN = "test" } stages { stage('Forces') { steps { script { sh """ docker pull fluidattacks/forces:latest docker run fluidattacks/forces:latest forces --token ${TOKEN} --repo-name """ } } } }} ``` ### GitHub On **GitHub**, the configuration file should look like this: ``` jobs: forces: runs-on: ubuntu-latest container: image: fluidattacks/forces:latest env: TOKEN: REPO_NAME: steps: - name: Run Agent check run: forces --token ${TOKEN} --strict --repo-name ${REPO_NAME} ``` ### Harness On **Harness**, include the following in the YAML file that defines your pipeline: ``` stages: - stage: name: identifier: AgentStage type: CI spec: cloneCodebase: false infrastructure: type: KubernetesDirect spec: connectorRef: namespace: default execution: false steps: false - step: false type: Run name: identifier: RunAgentCheck spec: connectorRef: image: fluidattacks/forces:latest shell: Bash command: | forces --token ${secrets.getValue("AGENT_TOKEN")} ``` > [!TIP] > > Note that `<stage-name>`, `<your-k8s-connector-id>`, `<stage-name>`, and `<your-docker-connector-id>` are defined by you, and this configuration assumes that the [CI Gate token](https://help.fluidattacks.com/portal/en/kb/articles/prevent-the-deployment-of-builds-with-vulnerabilities#Generate_the_DevSecOps_token) is a secret named `AGENT_TOKEN`. ## Execution logs and results After any execution of the CI Gate, you can also check its logs on the **DevSecOps** tab of Fluid Attacks' platform. **Organization > Groups > GroupName > DevSecOps**. Get more information about this section in the article "[Prevent the deployment of builds with vulnerabilities](https://help.fluidattacks.com/portal/en/kb/articles/prevent-the-deployment-of-builds-with-vulnerabilities)." You can also get the report in JSON format with the `--output` CLI argument. For example, running CI Gate with `--output report.json` creates a `report.json` file with this structure: ``` { "findings": [ { "identifier": "111111111", "title": "083. XML injection (XXE)", "status": "vulnerable", "exploitability": 0.94, "severity": 3.2, "url": "https://app.fluidattacks.com/orgs/my-org/groups/my-group/vulns/111111111/locations", "vulnerabilities": [ { "type": "DAST", "where": "192.168.100.105", "specific": "3636", "state": "vulnerable", "severity": 3.2, "report_date": "2023-08-13 09:58:38-05:00", "root_nickname": "my-root", "exploitability": 0.94, "compliance": false } ] } ], "summary": { "vulnerable": { "dast": 1, "sast": 0 }, "overall_compliance": false, "elapsed_time": "0.4392 seconds", "total": 1 }} ``` ## Troubleshooting 1. Please make sure that your Docker engine version is >= 20.10.10. ``` docker --versionDocker version 20.10.10, build v20.10.10 ``` This is important because CI Gate uses a [GNU libc](https://www.gnu.org/software/libc/) version >= 2.34, and the default [seccomp](https://en.wikipedia.org/wiki/Seccomp) profile of Docker <= 20.10.9 [is not adjusted to support the clone syscall](https://github.com/moby/moby/blob/v20.10.9/profiles/seccomp/default.json) of GNU libc introduced in version 2.34. 1. Please check that your Docker installation is working. If it is, you should be able to run a Hello World: ``` docker run hello-worldHello from Docker!This message shows that your installation appears to be working correctly.... ``` Otherwise, please refer to the [Docker documentation](https://docs.docker.com/) and the [Docker installation steps](https://docs.docker.com/engine/install/). 1. If you still experience issues running CI Gate after following the steps above, feel free to contact [help@fluidattacks.com](mailto:help@fluidattacks.com/). Please include in the report as much information as possible to help to reproduce the problem, for example: - The Docker engine and Server version: `docker info` - The host fingerprint: `uname -a` - The value of `docker inspect fluidattacks/forces:latest` - The organization, group, and repository name you are executing the agent on. ### Footnotes 1. [Grace period policy](https://help.fluidattacks.com/portal/en/kb/articles/manage-general-policies#Grace_period_where_newly_reported_vulnerabilities_will_not_break_the_build) 1. [Minimum breaking severity policy](https://help.fluidattacks.com/portal/en/kb/articles/manage-general-policies#Minimum_CVSS_v3_1_score_of_an_open_vulnerability_to_break_the_build)