Introduction

Forces is the product responsible for the client-side part of the DevSecOps agent. It uses the Integrates API to communicate with the back-end.

Contributing

Please read the contributing page first.

Internals

1. Forces is written in Python, with the rich library providing colors, tables and formatting. An image is built and then deployed to the Fluid Attacks DockerHub page.

Tip

You can try out your own image of Forces by running the following command after the deployContainerManifest/forcesDev job in the pipeline is done:

docker pull fluidattacks/forces:<youruseratfluid> &&
docker run --rm fluidattacks/forces:<youruseratfluid> forces

Note

Forces sends some telemetry to Bugsnag, where developers can use it to improve exception handling and enhance the program’s logic to prevent unexpected crashes. Remember, stability is paramount!

Product structure

• Directorysrc

  • Directoryapis

    • Directoryintegrates

      • api.py GraphQL operations made to the Integrates API are found here
      • client.py GraphQL client, timeout and retry parameters are defined here
  • Directorycli

    • __init__.py Defines the CLI flags and help information
  • Directorymodel/ NamedTuple class definitions for data and the reports

    • …
  • Directoryreport/ Data parsers, validations and report formatting

    • …
  • Directoryutils/ General utils including the strict mode evaluation

    • …
  • __init__.py Application entrypoint
• Directorytest/ Unit and functional tests

  • …

Getting Started

1. Configure your Development Environment.

2. When prompted for an AWS role, choose dev, and when prompted for a Development Environment, pick forces.

3. Run this command within the universe/forces directory:

   nix run .

   This will build and run the Forces CLI application, including the changes you’ve made to the source code. Most of the time you’ll be running Forces this way.

Note

You will need to pass the Forces token to the CLI, which can be generated locally and from ephemeral environments.

Linting and testing

To lint and format tests and source code, run the following command:

nix run .#forces-lint

To run the tests, use:

nix run .#forces-test

Checking the output

Forces can be pointed to your local or ephemeral Integrates instances, to do so, set the API_ENDPOINT variable:

• Local environment:

    export API_ENDPOINT=http://localhost:8001/api

• Ephemeral environment:

    export API_ENDPOINT=http://<youruseratfluid>.app.fluidattacks.com/api

The output can be seen in the DevSecOps table of the group in the instance you pointed Forces to.

See also

• httpx AsyncClient used as as transport by gql to communicate with the Integrates API.