Skip to main content

DevSecOps Installation

You can use the DevSeCops agent on any x86_64 machine in which Docker is installed. You can also integrate the agent into your CI/CD to ensure that your software is built and shipped without previously reported vulnerabilities in our Fluid Attacks' platform.

In order to use The Agent, there are some requirements:

  1. Make sure you have a DevSecOps agent token.

    This token can be generated in our platform scope section (Organization>Groups>GroupName>Scope), where you will find the DevSecOps Agent Token section.

DevSevOps Generation Section

Click on the Manage Token button and a pop-up will appear where you can Generate the token or click on Reveal Token in case you already generated one.

DevSevOps Generation Modal

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.

  1. If you want to run The 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 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, be it in your local machine or your CI/CD pipeline. The arguments are:

  • --token: Your DevSecOps agent token (required).
  • --dynamic / --static: Check for only DAST / SAST vulnerabilities respectively.
  • --strict / --lax: Run forces in either strict or lax mode (default --lax).
  • --verbose: Set the level of detail of the report (default -vv).
    • -v: Show non-compliant, vulnerable locations that would break policy12 and thus the build in Strict mode.
    • -vv: Show vulnerable finds regardless of policy compliance.
  • --repo-name: Git repository nickname.
  • --repo-path: Git repository path.
  • --breaking: Strict mode severity customization. Vulnerable locations with a severity below this threshold will not break the pipeline. This option takes values between 0.0 (recommended) all the way up to 10.0.
  • --output: Outputs the report to a local file as a formatted JSON, e.g. --output report.json.
  • --feature-preview: Enables the feature preview mode.

Note: Strict mode customization like severity thresholds and grace periods for new locations can also be set in the platform organization's Policies tab. 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:new forces --help

If you're running the Agent via makes, the command would be:

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

Run the Agent on your local machine​

Here you will find some examples running the agent on your 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 to download all the dependencies of the Agent through the command:

   docker pull fluidattacks/forces:new

To run the container here are some examples:

  • To check all finds including static and dynamic:

    docker run --rm -ti fluidattacks/forces:new forces --token <your-token> -vv

  • To check for static locations only:

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

  • To check for dynamic locations only:

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

  • Verify the locations of a specific repository:

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

  • To break the pipeline only if vulnerable locations with a severity of and above 4.5 are found:

    docker run --rm -ti fluidattacks/forces:new 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.

tip

There's another way to run the Agent in your local machine through the use of makes, our very own framework. Just follow the installation procedure here and run the Agent with the command:

m gitlab:fluidattacks/universe@trunk /integrates/forces --token <your-token>

Plus any other arguments you wish. The arguments and expected behavior are exactly the same as what you'd get running the docker image. You can visualize the report in your terminal and in the DevSecOps table. As mentioned above, to see the available arguments just run

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

Run the Agent on your CI/CD​

If you want to run the Agent from your Repository's pipeline, we present the following examples:

In GitLab add these lines to your .gitlab-ci.yml

forces:
  image:
    name: fluidattacks/forces:new
  script:
    - forces --token <your-token> --strict --repo-name <repository name>

In Azure DevOps add these lines to you configuration file:

jobs:
  - job: Fluidattacks Agent
    pool:
      vmImage: "ubuntu-latest"
    steps:
      - script: |
          docker pull fluidattacks/forces:new \
            && docker run fluidattacks/forces:new forces --token <your-token>

In 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:new
            docker run fluidattacks/forces:new forces --token ${TOKEN} --repo-name <repository name>
          """
        }
      }
    }
  }
}

In GitHub, the configuration file should look like this:

jobs:
  forces:
    runs-on: ubuntu-latest
    container:
      image: fluidattacks/forces:new
      env:
        TOKEN: <your-token>
        REPO_NAME: <repository name>
    steps:
      - name: Run Agent check
        run: forces --token ${TOKEN} --strict --repo-name ${REPO_NAME}
tip

You can also use the makes container to run the Agent in your pipeline, in the examples above, simply switch the image/container with: ghcr.io/fluidattacks/makes/arm64:latest

And the command to run with: m gitlab:fluidattacks/universe@trunk /integrates/forces --token <your-token>

Plus any other arguments you wish. The arguments and expected behavior are exactly the same as what you'd get running the Agent's container directly.

Execution logs and results​

After any execution of the Agent, you can check out its logs on Fluid Attacks' platform as well, on the DevSecOps tab. Organization>Groups>GroupName>DevSecOps. For more information about this section, click here.

You can also get the report as a formatted JSON 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
  }
}

Troubleshooting​

  1. 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.

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

  3. If you're running the Agent via makes in your local machine, you can update makes with the command nix-env -if https://github.com/fluidattacks/makes/archive/latest.tar.gz.

  4. If after following the steps above you still experience issues running the agent, feel free to contact us at [email protected] and we'll 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:new.
    • The organization, group, and repository name you are executing the agent on.
  1. Grace period policy.↩
  2. Minimum breaking severity policy.↩
Last updated on