Setup Policy

capsules:
  - name: "sampleScheme" # scheme name as defined in the manifest
    parameters:          # defined parameters that are declared in the manifest
      - sample: 1
      - param: 2.3
      - names: "four"
    start_events:        # specify which kinds of flows to bind to - all fields optional
      - src_ips:
        - "203.0.113.10"
        dst_ips:
        - "203.0.113.20"
        sports:
        - 80
        dports:
        - 80
        count:           # match flow only when a certain packet count is reached
          count_value: 5 # amount of packets to be counted
          time: 100      # sliding time frame (in milliseconds) for packet count to be reached
      - src_ips:
        - "!203.0.113.50"     # ip addresses may be negated
        dst_ip_paths:    # ip addresses may be listed in separate YAML files
        - "/path/to/list.yaml"
        aggr:
          aggr_value: 90 # data amount (in bytes) to be reached
          time: 100      # sliding time frame (in milliseconds) for data amount to be reached

The setup policy defines when to run which capsules, with which parameters.

It has no default path, so it must be defined in the config file or using the -policy flag.

System Config

network_interface: "eth0"  # network interface Waterfall binds to
capsule_addresses:         # address other nodes for communication via broadcasting and sending messages
  other: "203.0.113.1:50051"
  nodes: "203.0.113.2:50051"
  to: "203.0.113.3:50051"
  communicate: "203.0.113.4:50051"
  with: "203.0.113.5:50051"
policy_file: "/default/policy/file.yaml"
key_dir: "/default/key/directory"
manifest_dir: "/default/manifest/directory"
script_dir: "/default/script/directory"

If not changed via the -config flag, the path to the system config file defaults to ~/.config/waterfall/config.yaml.

The only required entry in the system config file is the network interface. The other fields are optional.

The default paths defined in the file can be overwritten with their respective CLI flags.

Manifest

name: "sampleScheme"      # name of the scheme
capsule_type: "Embedding" # "Embedding" or "Detection"
flow_name: "DataFlow"     # name of the initially bound flow
exclude:                  # optional - specify additional flows to reserve
  - Reverse               # reserve the opposite direction of the initially bound flow
parameters:               # optional - declare parameters to be defined in the policy and passed to the capsules - can be int, float, or string
  - sample: int
  - param: float
  - names: string

For each scheme, a manifest has to be created, in which general parameters are defined. The name is what the scheme is referred to as throughout Waterfall, including by the setup policy. The scheme script is also matched using the name; its file must be named after the scheme name.

Setting the capsule type carefully is important, since only embedding capsules can affect flows. One flow may be captured by multiple detection capsules, but embedding capsules require exclusive control.

The path to the manifests and their scripts defaults to ./schemes, traversing all subdirectories.