Install the CI Agent to break the build

Alert: The Docker tag new for the agent 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 the CI Agent on any x86_64 machine in which Docker is installed. You can also integrate the agent into your CI/CD to ensure your software is built and shipped without previously reported vulnerabilities in our platform.

In order to use the CI Agent, there are some requirements:

Make sure you have a DevSecOps agent token. This token can be generated in our platform's Scope section (Organization>Groups>GroupName>Scope), where you will find the DevSecOps agent section.

Find the DevSecOps agent token management option on the Fluid Attacks platform

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 DevSecOps agent token on the Fluid Attacks platform

Note: The DevSecOps 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 agent token is the users' work. The roles that can generate this token are User, User Manager and Vulnerability Manager.

If you want to run the CI Agent on your local machine:

Make sure your execution environment has the required dependencies: Docker (>= 20.10.10).
Install Docker by following the official guide.
(New) You can run the agent with Makes instead; more information in the tips at the end of each section below.

Note: You can also run the CI Agent 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.

Arguments

You can customize the agent's behavior according to your necessities, whether in your local machine or your CI/CD pipeline. The arguments are the following:

Required

--token: your DevSecOps agent 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.

--cvss: indicates which version of CVSS the CI Agent should use to break the build.
- 3.1: the agent will break the build according to the severity calculated using CVSS 3.1.
- 4.0: the agent will break the build according to the severity calculated using CVSS 4.0 (default option).

--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.
--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 the agent by repeating --repo-path, e.g., --repo-path path1 --repo-path path2 --repo-path "path3/*" and so on.

Warning: The agent 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 SAST vulnerabilities from the Fluid Attacks' platform.

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,2, 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.

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, the agent 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 agent will consider the lower severity value between the one specified in the policy and the one you defined in the argument.

Tip: You can check the agent's arguments in your container by running the following command:

docker run --rm -ti fluidattacks/forces:latest forces --help

If you're running the agent via Makes, the command would be this:

m gitlab:fluidattacks/universe@trunk /integrates/forces --help

Run the CI Agent on your local machine

Here, you will find examples of running the agent 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, we need to run the Docker image, which will help us download all the dependencies of the agent 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 <your-token> -vv

To check static locations only:

docker run --rm -ti fluidattacks/forces:latest forces --static --strict --token <your-token>

To check dynamic locations only:

docker run --rm -ti fluidattacks/forces:latest forces --dynamic --strict --token <your-token>

To verify the locations of a specific repository:

docker run --rm -ti fluidattacks/forces:latest forces --dynamic --strict --repo-name <nickname repo> --token <your-token>

To break the pipeline only if vulnerable locations 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 <your-token>

                    

Tip: The --rm and --ti parameters are optional. Thus, you can define the best way according to your context.

You can also run the CI Agent on your local machine using our Makes framework. Just follow the installation procedure and run the agent with this command:

m gitlab:fluidattacks/universe@trunk /integrates/forces --token <your-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 /integrates/forces --help

Run the CI Agent on your CI/CD

If you want to run the agent from your repository's pipeline, the following are some examples.

Tip: You can also use the Makes container to run the agent in your pipeline; for the examples below, simply switch the image/container to this: ghcr.io/fluidattacks/makes/arm64:latest, and the command to run to this: m gitlab:fluidattacks/universe@trunk /integrates/forces --token <your-token>.

Plus, any other arguments you wish. The arguments and expected behavior are the same as you would get running the agent's container directly.

GitLab

On GitLab, add these lines to your .gitlab-ci.yml:

forces:
  image:
    name: fluidattacks/forces:latest
  script:
    - forces --token <your-token> --strict --repo-name <repository 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 <your-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 <repository name>
          """
        }
      }
    }
  }
}

GitHub

On GitHub, the configuration file should look like this:

jobs:
  forces:
    runs-on: ubuntu-latest
    container:
      image: fluidattacks/forces:latest
      env:
        TOKEN: <your-token>
        REPO_NAME: <repository 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: <stage-name>
        identifier: AgentStage
        type: CI
        spec:
          cloneCodebase: false
          infrastructure: 
            type: KubernetesDirect
            spec:
              connectorRef: <your-k8s-connector-id>
              namespace: default
          execution: false
            steps: false
              - step: false
                  type: Run
                  name: <step-name>
                  identifier: RunAgentCheck
                  spec:
                    connectorRef: <your-docker-connector-id>
                    image: fluidattacks/forces:latest
                    shell: Bash
          command: |
            forces --token ${secrets.getValue("AGENT_TOKEN")}

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 Agent token is a secret named AGENT_TOKEN.

Execution logs and results

After any execution of the CI Agent, 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 our article "Prevent the deployment of builds with vulnerabilities."

You can also get the report in JSON format with the --output CLI argument. For example, running the agent with --output report.json will create 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
  }
}

If the agent is executed from a terminal with Makes, the report.json file will be stored in the current working directory. However, for it to be placed in a container and retrievable from there, a volume must be added to such a container. To do this, you must use the command docker run -v /path/to/output/dir --rm container-image:latest forces.

Troubleshooting

Please make sure that your Docker engine version is >= 20.10.10.
```
docker --version

Docker version 20.10.10, build v20.10.10
```
This is important because the agent uses a GNU libc version >= 2.34, and the default seccomp profile of Docker <= 20.10.9 is not adjusted to support the clone syscall of GNU libc introduced in version 2.34.
Please check that your Docker installation is working. If it is, you should be able to run a Hello World:
```
docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.
...
```
Otherwise, please refer to the Docker documentation and the Docker installation steps.
If you're running the agent via Makes on your local machine, you can update Makes with the command nix-env -if https://github.com/fluidattacks/makes/archive/latest.tar.gz.
If you still experience issues running the agent after following the steps above, feel free to contact us at help@fluidattacks.com, and we will do our best to help.

Please include in the report as much information as possible to help us 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.

Install the CI Agent to break the build | Fluid Attacks Help