Skip to content

Authoring Analysis Rules

Jump to bottom
Gabe Stocco edited this page Feb 6, 2024 · 14 revisions

Analysis Rules

Attack Surface Analyzer allows the user to specify a set of Rules which contain triggers to flag results found by Attack Surface Analyzer. This page documents the format for specifying those rules.

Contributions

If you have an interesting rule you think would make a good fit for the default ruleset please open an issue with your contribution.

For ASA 2.3

Starting with ASA 2.3 we use the Object Analysis Toolkit library, which was originally developed as the Analyzer engine in ASA. The main user facing change is the changes to the Operation enum. If you have custom rules written for ASA 2.2 they will need to be slightly modified for 2.3.

Operation Enum Changes

The Operation Enum previous to 2.3 was called OPERATION and the earlier values map to new values like this:

CUSTOM => Custom
REGEX => Regex
EQUALS => Equals
LT => LessThan
GT => GreaterThan
CONTAINS => Contains
WAS_MODIFIED => WasModified
ENDS_WITH => EndsWith
STARTS_WITH => StartsWith
CONTAINS_ANY => ContainsAny
IS_NULL => IsNull
IS_TRUE => IsTrue
IS_BEFORE => IsBefore
IS_AFTER => IsAfter
IS_EXPIRED => IsExpired
CONTAINS_KEY => ContainsKey

Default Rules

Attack Surface Analyzer comes with a default set of rules you can view here.

Specifying Rules

Rules are defined in a JSON file provided by the user or embedded in the build. The Rules file is Deserialized into a RuleFile Object and processed by the Analysis engine against each object with a matching Result Type.

This is a simple analyses.json file with a single rule.

{
  "Rules": [
    {
      "Name": "Privileged ports",
      "Description": "Flag when privileged ports are opened.",
      "Flag": "WARNING",
      "ResultType": "PORT",
      "Clauses": [
        {
          "Field": "port",
          "Operation": "LT",
          "Data": [
            "1024"
          ]
        }
      ]
    }
  ],
 "DefaultLevels": {
      "PORT": "INFORMATION",
      "FILE": "DEBUG",
      "SERVICE": "INFORMATION",
      "CERTIFICATE": "INFORMATION",
      "USER": "INFORMATION",
      "REGISTRY": "DEBUG",
      "FIREWALL": "INFORMATION",
      "COM": "INFORMATION",
      "LOG": "DEBUG"
  }
}

Rules

The Rules section is a List of ASA Rules which derive from OAT Rule. If no Rules are present, only the DefaultLevels (if present) will be applied.

DefaultLevels

The DefaultLevels, if present, override the hardcoded default information level of INFORMATION.

Rule Basics

A Rule contains

  • a Flag (ANALYSIS_RESULT_TYPE)
  • a Name
  • a ResultType (RESULT_TYPE specifying a CollectObject type the Rule should apply to)
  • an optional Description
  • an optional list of 0 or more Clauses (Clause)
  • an optional boolean Expression
  • an optional list of Platforms to restrict the rule to (PLATFORM)
  • an optional list of ChangeTypes to restrict the rule to (CHANGE_TYPE)

Rule matching

A Rule matches an Object when:

  • The Object's type maps to the specified ResultType AND any of
    1. the rule has no Clauses
    2. the rule has no Expression AND all its Clauses are true
    3. the evaluation of the Expression is true

Flags

The Flag levels are defined in ANALYSIS_RESULT_TYPE. Results will be flagged with the most severe flag of any of the rules applied to them.

Flag levels in increasing order of severity are:

NONE
VERBOSE
DEBUG 	
INFORMATION
WARNING
ERROR 	
FATAL

Clause Basics

A Clause contains:

  • An Operation (Operation)
  • A Field that the Clause applies to. Any Public Property or Sub-property of Any Object which inherits from CollectObject.
  • An optional Label (required if using an Expression in the associated Rule). The Label may contain any characters other than spaces and parenthesis.
  • An optional List, Data as appropriate depending on the Operation.
  • An optional Dictionary, DictData as appropriate depending on the Operation.

Expressions

The Expression in a rule is a user specified boolean expression across the defined Clauses' Labels in the Rule.

These are some examples of Valid Expressions:

FOO
FOO AND BAR
FOO OR BAR NAND BAZ (BAT123 XOR $B@A%N)

Expressions can be created using any of the standard boolean operators in addition to parenthesis.

OR
AND
NOR
NAND
XOR
NOT

Verifying Your Rules

To verify your rules run asa verify --AnalysisFile path/to/file.json. You should receive a list of any found issues in your rule definitions.

Rule Examples

The following examples are JSON snippets from the default ruleset.

Simple Rule

This is an example of a simple rule which flags open ports below 1024.

{
      "Name": "Privileged ports",
      "Description": "Flag when privileged ports are opened.",
      "Flag": "WARNING",
      "ResultType": "PORT",
      "Clauses": [
        {
          "Field": "port",
          "Operation": "LessThan",
          "Data": [
            "1024"
          ]
        }
      ]
}

Rule With Expression

This is an example of a more complicated rule which uses an OR based Expression in order to match the hosts file on Windows, Linux and Mac systems with one rule.

{
      "Name": "Modified Hosts File",
      "Description": "Flag when the hosts file is modified.",
      "Flag": "WARNING",
      "ChangeTypes": [
        "MODIFIED"
      ],
      "ResultType": "FILE",
      "Expression": "WINDOWS OR NIX",
      "Clauses": [
        {
          "Label": "WINDOWS",
          "Field": "Path",
          "Operation": "Regex",
          "Data": [
            "[A-Z]:\\\\Windows\\\\System32\\\\drivers\\\\etc\\\\hosts"
          ]
        },
        {
          "Label": "NIX",
          "Field": "Path",
          "Operation": "Equals",
          "Data": [
            "/etc/hosts"
          ]
        }
      ]
    }

Advanced Scenarios

ASA Rules inherit from the Object Analysis Toolkit Rule class and all OAT functionality is available.

For more information see Authoring Rules on the OAT Wiki

For ASA 2.2 and earlier

Default Rules

Attack Surface Analyzer comes with a default set of rules you can view here.

Specifying Rules

Rules are defined in a JSON file provided by the user or embedded in the build. The Rules file is Deserialized into a RuleFile Object and processed by the Analysis engine against each object with a matching Result Type.

This is a simple analyses.json file with a single rule.

{
  "Rules": [
    {
      "Name": "Privileged ports",
      "Description": "Flag when privileged ports are opened.",
      "Flag": "WARNING",
      "ResultType": "PORT",
      "Clauses": [
        {
          "Field": "port",
          "Operation": "LT",
          "Data": [
            "1024"
          ]
        }
      ]
    }
  ],
 "DefaultLevels": {
      "PORT": "INFORMATION",
      "FILE": "DEBUG",
      "SERVICE": "INFORMATION",
      "CERTIFICATE": "INFORMATION",
      "USER": "INFORMATION",
      "REGISTRY": "DEBUG",
      "FIREWALL": "INFORMATION",
      "COM": "INFORMATION",
      "LOG": "DEBUG"
  }
}

Rules

The Rules section is a List of Rules. If no Rules are present, only the DefaultLevels (if present) will be applied.

DefaultLevels

The DefaultLevels, if present, override the hardcoded default information level of INFORMATION.

Rule Basics

A Rule contains

  • a Flag (ANALYSIS_RESULT_TYPE)
  • a Name
  • a ResultType (RESULT_TYPE specifying a CollectObject type the Rule should apply to)
  • an optional Description
  • an optional list of 0 or more Clauses (Clause)
  • an optional boolean Expression
  • an optional list of Platforms to restrict the rule to (PLATFORM)
  • an optional list of ChangeTypes to restrict the rule to (CHANGE_TYPE)

Rule matching

A Rule matches an Object when:

  • The Object's type maps to the specified ResultType AND any of
    1. the rule has no Clauses
    2. the rule has no Expression AND all its Clauses are true
    3. the evaluation of the Expression is true

Flags

The Flag levels are defined in ANALYSIS_RESULT_TYPE. Results will be flagged with the most severe flag of any of the rules applied to them.

Flag levels in increasing order of severity are:

NONE
VERBOSE
DEBUG 	
INFORMATION
WARNING
ERROR 	
FATAL

Clause Basics

A Clause contains:

  • An Operation (OPERATION)
  • A Field that the Clause applies to. Any Public Property or Sub-property of Any Object which inherits from CollectObject.
  • An optional Label (required if using an Expression in the associated Rule). The Label may contain any characters other than spaces and parenthesis.
  • An optional List, Data as appropriate depending on the Operation.
  • An optional Dictionary, DictData as appropriate depending on the Operation.

Expressions

The Expression in a rule is a user specified boolean expression across the defined Clauses' Labels in the Rule.

These are some examples of Valid Expressions:

FOO
FOO AND BAR
FOO OR BAR NAND BAZ (BAT123 XOR $B@A%N)

Expressions can be created using any of the standard boolean operators in addition to parenthesis.

OR
AND
NOR
NAND
XOR
NOT

Verifying Your Rules

To verify your rules run asa verify --filename path/to/file.json. You should receive a list of any found issues in your rule definitions.

Rule Examples

The following examples are JSON snippets from the default ruleset.

Simple Rule

This is an example of a simple rule which flags open ports below 1024.

{
      "Name": "Privileged ports",
      "Description": "Flag when privileged ports are opened.",
      "Flag": "WARNING",
      "ResultType": "PORT",
      "Clauses": [
        {
          "Field": "port",
          "Operation": "LT",
          "Data": [
            "1024"
          ]
        }
      ]
}

Rule With Expression

This is an example of a more complicated rule which uses an OR based Expression in order to match the hosts file on Windows, Linux and Mac systems with one rule.

{
      "Name": "Modified Hosts File",
      "Description": "Flag when the hosts file is modified.",
      "Flag": "WARNING",
      "ChangeTypes": [
        "MODIFIED"
      ],
      "ResultType": "FILE",
      "Expression": "WINDOWS OR NIX",
      "Clauses": [
        {
          "Label": "WINDOWS",
          "Field": "Path",
          "Operation": "REGEX",
          "Data": [
            "[A-Z]:\\\\Windows\\\\System32\\\\drivers\\\\etc\\\\hosts"
          ]
        },
        {
          "Label": "NIX",
          "Field": "Path",
          "Operation": "EQ",
          "Data": [
            "/etc/hosts"
          ]
        }
      ]
    }
Clone this wiki locally