ARMR DNS Rule

Support for API Protect was added to this rule in ARMR 2.9. Please see the API Protect Directives page in the ARMR documentation for information on how to configure this rule for API endpoint protection.

Overview

The DNS security rule provides the ability to log and restrict DNS lookups performed by any application running on the Java Virtual Machine. By restricting DNS lookups to known and trusted domains, abuse of the DNS service can be prevented.

The DNS rule begins with a dns keyword and ends with an enddns keyword, it must contain the rule name as a parameter and this is an arbitrary string, hence it needs to be surrounded with double-quotes.

The rule cannot contain duplicate statements, however multiple dns rules are allowed in the same ARMR application, and the order of statements inside the dns rule does not matter.

Given (Condition)

lookup

The lookup takes a single parameter (string literal) where valid values are a quoted-hostname, a quoted-IPv4 address, or the constant any indicating any hostname or IPv4 address.

lookup("example.org")
lookup("127.0.0.1")
lookup(any)

IPv6 addresses are not currently supported.

Then (Action)

An Action accepts a message as its parameter.

An action may, optionally, specify a severity. The value of severity may be an integer in the range of 0-10(0 is the lowest level and 10 is the highest level) or one of Low, Medium, High or Very-High(case insensitive). The default severity is unknown.

protect	The DNS lookup is not allowed to proceed. If configured, a log message is generated with details of the event.
detect	Monitoring mode: the application behaves as normal, the DNS lookup is allowed to proceed. If configured, a log message is generated detailing that the agent has detected an attempt to carry out a DNS lookup. A log message must be specified with this action.
allow	Can be used to allow specific IP addresses/hostnames to be looked up without being blocked by other DNS rule(s).

As part of the action statement, the user may optionally specify the parameter stacktrace: “full”. When this parameter is specified, the stacktrace of the location of the attempted exploit is included in the security log entry.

Examples

DNS rule with quoted-hostname.

app("DNS lookup mod"):
  requires(version: ARMR/2.7)
  dns("Blocking address resolution for example.org"):
    lookup("example.org")
    protect(message: "dns lookup occurred for example.org", severity: 8)
  enddns
endapp

DNS rule with quoted-IPv4 address.

app("DNS lookup mod"):
  requires(version: ARMR/2.7)
  dns("Detecting address resolution for localhost"):
    lookup("127.0.0.1")
    detect(message: "dns lookup event", severity: 6)
  enddns
endapp

DNS rule with the constant any.

app("DNS lookup mod"):
  requires(version: ARMR/2.7)
  dns("Detecting address resolution for any host/ip"):
    lookup(any)
    detect(message: "dns lookup event", severity: 4)
  enddns
endapp

Logging

A log entry similar to the following is generated when the below dns rules identify a DNS lookup:

<10>1 2021-03-22T12:58:06.136Z userX_system java 17522 - - CEF:0|ARMR:ARMR|ARMR|2.7|DNS Test App detect|Execute Rule|High|rt=Mar 22 2021 12:58:06.135 +0000 dvchost=jenkins-qa-secondary-centos.aws.example.org procid=17522 appVersion=1 ruleType=dns securityFeature=dns act=detect msg=Walter hostname=example.org

Further Examples

DNS rule with the stacktrace also logged.

app("DNS lookup mod"):
  requires(version: ARMR/2.7)
  dns("Detecting address resolution for localhost"):
    lookup(any)
    protect(message: "dns lookup event", severity: 9, stacktrace: "full")
  enddns
endapp

Logging

<10>1 2021-04-01T12:31:39.637+01:00 userX_system java 174476 - - CEF:0|ARMR:ARMR|ARMR|2.7|DNS Test App protect|Execute Rule|High|rt=Apr 01 2021 12:31:39.636 +0100 dvchost=ckang-XPS-15-9570 procid=174476 appVersion=1 ruleType=dns securityFeature=dns act=protect msg=dns lookup event
stacktrace=walter.apps.DNSLookupApp.main(Container-1)(DNSLookupApp.java:94)\nsun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\nsun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)\nsun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\njava.lang.reflect.Method.invoke(Method.java:498)\njava.lang.Thread.run(Container-1)(Thread.java:876)\njava.lang.Thread.begin(Container-1)(Thread.java:897)\njava.lang.Thread.invokeRun(Container-1)(Thread.java:883)\njava.lang.Thread$ThreadHandler.invokeRun(Container-1)(Thread.java:55) hostname=alto.aws.example.org

Logging On/Off Example

In the following example, logging is switched ON in the protect rule by the inclusion of the protect action message attribute. As the message attribute is defined as an empty string (""), a default message will be included in the security event msg extension. The allow rule allows DNS lookups of the specified hostname in the lookup parameter. Logging is switched OFF in the allow rule by the omission of the action message attribute.

app("DNS lookup mod"):
  requires(version: ARMR/2.7)

  dns("Blocking address resolution for any host/ip. Logging ON"):
    lookup(any)
    protect(message: "", severity: 7)
  enddns

  dns("Allowing address resolution for example.org. Logging OFF"):
    lookup("example.org")
    allow(severity: 4)
  enddns
endapp