Documentation

Overview


Thank you for checking out the Adversa Labs Documentation. This documentation is designed to assist in the installation, utilization and troubleshooting of Adversa SDK Tools. At times, you may need further assistance if something is either not covered or clear in the documentation. In these instances, you can reach out to us at support@adversalabs.com.

Many thanks,
Customer Support, Adversa Labs LLC.

Prerequisites

Supported Operating Systems

The following operating systems and their versions are supported by Adversa SDK Tools:

Name Architecture(s) Version(s)
Arch Linux x86_64 2018
CentOS x86_64 7
Debian x86_64 9
Fedora x86_64 28
MacOS x86_64 High Sierra
RHEL x86_64 7
Ubuntu x86_64 16.04 LTS
Windows x86_64 10
Supported Programming Languages

The following programming languages are supported for security testing by Adversa SDK Tools:

Name Runtime Version(s)
Java jvm 7, 8, 9, 10

Installation

Linux Operating Systems

Verify you have curl installed by running the following script in your terminal:

bash-3.2$ curl --version

You should see output similar to the following if curl is installed:

curl 7.29.0 (x86_64-redhat-linux-gnu) libcurl/7.29.0 NSS/3.28.4 zlib/1.2.7 libidn/1.28 libssh2/1.4.3
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp scp sftp smtp smtps telnet tftp 
Features: AsynchDNS GSS-Negotiate IDN IPv6 Largefile NTLM NTLM_WB SSL libz unix-sockets

Run the following script in your terminal to install Adversa SDK Tools:

bash-3.2$ curl https:///install.sh -sSf | sh

You should see output similar to the following if installation was successful:

Congratulations! You have successfully installed Adversa SDK Tools.

To get started you will need the bin directory ($HOME/.adversa/bin) in your PATH
environment variable. Next time you login this will be done automatically.

To configure your current shell run "source $HOME/.adversa/env". You can verify
that your current shell can locate the tools by running "adversa --help".

Please visit https:///install#overview for more information
on how to carry out security testing of your applications.

Sincerely,
Customer Support
support@adversalabs.com

Did the installation fail? Contact us at support@adversalabs.com.

MacOS Operating System

Verify you have curl installed by running the following script in your terminal:

bash-3.2$ curl --version

You should see output similar to the following if curl is installed:

curl 7.54.0 (x86_64-apple-darwin17.0) libcurl/7.54.0 LibreSSL/2.0.20 zlib/1.2.11 nghttp2/1.24.0
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp 
Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz HTTP2 UnixSockets HTTPS-proxy

Run the following script in your terminal to install Adversa SDK Tools:

bash-3.2$ curl https:///install.sh -sSf | sh

You should see output similar to the following if installation was successful:

Congratulations! You have successfully installed Adversa SDK Tools.

To get started you will need the bin directory ($HOME/.adversa/bin) in your PATH
environment variable. Next time you login this will be done automatically.

To configure your current shell run "source $HOME/.adversa/env". You can verify
that your current shell can locate the tools by running "adversa --help".

Please visit https:///install#overview for more information
on how to carry out security testing of your applications.

Sincerely,
Customer Support
support@adversalabs.com

Did the installation fail? Contact us at support@adversalabs.com.

Windows Operating Systems

Verify you have PowerShell installed by running the following script in your command prompt:

C:\Users\Adversa> PowerShell -Command $PSVersionTable

You should see output similar to the following if PowerShell is installed:

Name                           Value
----                           -----
PSVersion                      5.1.17134.165
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17134.165
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Run the following script in your terminal to install Adversa SDK Tools:

$ PowerShell -Command "Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString(\"https:///install.ps1\"))"

You should see output similar to the following if installation was successful:

Congratulations! You have successfully installed Adversa SDK Tools.

To get started you will need the bin directory (%USERPROFILE%\.adversa\bin) in your PATH
environment variable. Next time you open cmd.exe this will be done automatically.

To configure your current shell run "setx PATH %PATH%;%USERPROFILE%\.adversa\bin".
You can verify that your current shell can locate the tools by running "adversa --help".

Please visit https://www.adversalabs.com/install#overview for more information
on how to carry out security testing of your applications.

Sincerely,
Customer Support
support@adversalabs.com

Did the installation fail? Contact us at support@adversalabs.com.

Assessment

The assess command will allow you to passively monitor your application for security vulnerabilities using the SDK specified by the --sdk argument. This command need only be prefixed to the command you currently use to run your application. The format of the command is as follows:

$ adversa assess --sdk [name] -- [command]

Tools will fork and exec your command with all of the runtime configurations necessary to passively monitor application behaviors for security vulnerabilities using the SDK denoted by name. As you interact with your application, either manually or via automated scripts, behaviors indicative of vulnerabilities will be printed to stdout for your review.

Visit the knowledgebase to learn more about the security tests performed.

  • JVM
    Assess via Gradle Tests

    The Gradle Build Tool provides a means of automatically running unit and integration tests during the build process. Adversa SDK Tools will passively monitor your application for security vulnerabilities while you're executing your automated Gradle tests. The following example illustrates how to integrate passive security testing within your Gradle build.

    $ adversa assess --sdk jvm -- gradle build
    Assess via Maven Tests

    The Apache Maven project provides a means of automatically running unit and integration tests during the build process. Adversa SDK Tools will passively monitor your application for security vulnerabilities while you're executing your automated Maven tests. The following example illustrates how to integrate passive security testing within your Maven build.

    $ adversa assess --sdk jvm -- mvn verify
    Assess via Manual or 3rd Party Tests

    Many integration and regression tests are carried out manually or via the use of 3rd party tools or products. Passive security testing can be integrated in such cases by modifying how you start your Java application. Adversa SDK Tools will passively monitor your application for security vulnerabilities while you carry out your manual or 3rd party tests. The following example illustrates how to integrate passive security testing within your Java application.

    $ adversa assess --sdk jvm -- java -jar target/app-0.0.1-SNAPSHOT.jar

Policy

Overview

Adversa SDK Tools can be configured to enforce policies when performing passive security testing. Policies expose the ability to configure types of vulnerabilities that are included in or excluded from the assessment. In addition, vulnerabilities included in the assessment can be configured to break builds when running in CI/CD.

Location

Policy configuration files may live in one of two locations. By default, Adversa SDK Tools will attempt to load a local policy file in the current working directory. For Unix like systems, this is located at $(PWD)/.adversa/policy.json. For Windows, this is located at %CD%\.adversa\policy.json The local configuration file can be used to enforce application specific policies and should be committed alongside the target application source code.

In the event a local policy file does not exist, Adversa SDK Tools will attempt to load a user policy file in the user's home directory. For Unix like systems, this is located at $(HOME)/.adversa/policy.json. For Windows, this is located at %USERPROFILE%\.adversa\policy.json The user configuration file can be used to apply a policy for all assessments carried out by the user in the event no local policy file exists.

You may also specify the location of a policy file via the --policy argument when invoking the assess command. The following example will passively test a Java application with a policy file located at /opt/adversa/policy.json:

$ adversa assess --sdk jvm --policy /opt/adversa/policy.json -- mvn verify
Format

Policy files make use of the JavaScript Object Notation (JSON) format. This allows for simple key value pairs as well as more complex hierarchical relationships. A trimmed down version of the policy and its grammar looks as follows:

{
    "name": "...",
    "description": "...",
    "vulnerabilities": {
        "inclusions": {
            "operand": "...",
            "criteria": [ ... ]
        },
        "exclusions": {
            "operand": "...",
            "criteria": [ ... ]
        },
    },
    "build": {
        "failures": {
            "operand": "...",
            "criteria": [ ... ]
        }
    }
}
Preamble

The preamble both identifies and describes the intent of the policy writer. The following describes the preamble section.

    "name": "...",
    "description": "..."
  • name (String)  arbitrary string value used to identify the policy
  • description (String)  arbitrary string value used to describe the intent of the policy
Vulnerabilities

Vulnerabilities describes those vulnerabilities that should either be included or excluded from the assessment using the Selector type. The following describes the vulnerabilities section.

"vulnerabilities": {
    "inclusions": {
        "operand": "...",
        "criteria": [ ... ]
    },
    "exclusions": {
        "operand": "...",
        "criteria": [ ... ]
    },
}
  • inclusions (Selector)  selector under which a vulnerability should be included in the assessment.
  • exclusions (Selector)  selector under which a vulnerability should be excluded in the assessment.

Exclusions takes precedence over inclusions. If a vulnerability matches both the inclusions and exclusions selector, then the vulnerability will be excluded from the assessment.

Build

Build allows for the enforcement of certain behaviors when running an assessment as a part of a build, whether it be a local build or a CI/CD pipeline. The most significant capability is the specification of vulnerabilities under which the corresponding build should fail using the Selector type. The following describes the build section.

"build": {
    "failures": {
        "operand": "...",
        "criteria": [ ... ]
    }
}
  • failures (Selector)  selector describing those vulnerabilities that, if found, should fail a build
Selector

Selector allows for the specification of criteria used to match against a given vulnerability. A selector will contain an array of Criteria types as well as an operator describing the relationship amongst the criteria. The following describes the selector type.

"operand": "...",
"criteria": [ ... ]
  • operand (Enum)  value of "All" indicates all criteria must match whereas "Or" requires at least one criteria match
  • Criteria (Array)  array of Criteria types used to describe a vulnerability
Criteria

Criteria allows for the specification of one or more criterion used to match against a given vulnerability. Criteria will contain an array of Criterion types as well as an operator describing the relationship amongst the criterion. The following describes the criteria type.

"operand": "...",
"criterion": [ ... ]
  • operand (Enum)  value of "all" indicates all criterion must match whereas "or" requires at least one criterion match
  • Criterion (Array)  array of Criterion types used to describe a vulnerability
Criterion

Criterion allows for the specification of individual fields and values within a vulnerability. Criterion will contain an enumeration of type Property and an arbitrary string value. The following describes the criterion type.

"kind": "...",
"value": "..."
  • property (Enum)  one of "class", "hash", "severity", "file" or "signature"
  • value (String)  arbitrary string value used for matching against a particular property.

The "class" property is an enumeration whose values map directly to the name of vulnerability classes listed in the knowledgebase. By way of example, "XML External Entities" and "SQL Injection" are valid values for "class" as they contain a corresponding entry in the knowledgebase. Values are not case sensitive.

The "hash" property is a string representative of a hash that uniquely identifies a previously discovered vulnerability. Consult terminal output when running an assessment to locate the hash value of previously identified vulnerabilities.

The "severity" property is an enumeration whose values are one of "critical", "high", "medium", "low" or "none". These values are based off the Common Vulnerability Scoring System 3.0 . Values are not case sensitive.

The "file" property supports Unix style glob patterns. This allows for more complex wildcard matching capabilities. By way of example, a value of "foo/bar/**.*.js" will match all files ending with ".js" that are recursively found within the "foo/bar" directory.

The "signature" property is a string representative of a language specific method signature. By way of example, "com/company/MyObject.invoke(Ljava/lang/String;)V" is representative of a qualified method signature for the Java Virtual Machine.

Examples

The following section provides example policy files used to implement common use cases during passive security testing.

Only Report High Risk Vulnerabilities

The following sample policy only reports vulnerabilities if the corresponding severity is either "high" or "critical".

{
    "name": "high-risk-only",
    "description": "only report vulns whose severity is high or critical",
    "vulnerabilities": {
        "inclusions": {
            "operand": "or",
            "criteria": [
                {
                    "operand": "or",
                    "criterion": [
                        {
                            "property": "severity",
                            "value": "high"
                        },
                        {
                            "property": "severity",
                            "value": "critical"
                        }
                    ]
                }
            ]
        }
    }
}
Exclude Vulnerabilities in Test Code

The following sample policy excludes vulnerabilities that are found within test code. In this context, test code is defined as any vulnerability found in the com/company/repo/MockRepository.java file or any file in the com/company/test/ directory.

{
    "name": "exclude-test-code",
    "description": "exclude vulns by file known to be test code",
    "vulnerabilities": {
        "exclusions": {
            "operand": "or",
            "criteria": [
                {
                    "operand": "or",
                    "criterion": [
                        {
                            "property": "file",
                            "value": "com/company/repo/MockRepository.java"
                        },
                        {
                            "property": "file",
                            "value": "com/company/test/**/*"
                        }
                    ]
                }
            ]
        }
    }
}
Ignore Vulnerability Instances

The following sample policy indicates a set of previously identified vulnerabilities, represented by their hash, that are to be ignore from the assessment. Presumably these vulnerabilities are either an accepted risk or a false positive.

{
    "name": "ignore-vulnerability-instances",
    "description": "exclude vulns by hash known to be accepted or false",
    "vulnerabilities": {
        "exclusions": {
            "operand": "or",
            "criteria": [
                {
                    "operand": "or",
                    "criterion": [
                        {
                            "property": "hash",
                            "value": "e5c8399d"
                        },
                        {
                            "property": "hash",
                            "value": "cf4cc510"
                        },
                        {
                            "property": "hash",
                            "value": "71c19edb"
                        },
                        {
                            "property": "hash",
                            "value": "8c461c8c"
                        }
                    ]
                }
            ]
        }
    }
}
Fail Build on Criteria

The following sample policy will trigger a build to fail if a vulnerability with the class name "SQL Injection" or with a severity of "critical" is found. This sample can be used to identify and prevent the subsequent exposure of significant risk during the CI/CD build pipeline.

{
    "name": "fail-on-criteria",
    "description": "fail the build if sql injection or critical is found",
    "build": {
        "failures": {
            "operand": "or",
            "criteria": [
                {
                    "operand": "or",
                    "criterion": [
                        {
                            "property": "class",
                            "value": "SQL Injection"
                        },
                        {
                            "property": "severity",
                            "value": "critical"
                        }
                    ]
                }
            ]
        }
    }
}

Reporting

Overview

Adversa SDK Tools supports an ever-growing variety of ways in which vulnerabilities are reported. Vulnerabilities can be reported in terminal output, flat text files, JavaScript Object Notation (JSON) files and Hypertext Markup Language (HTML) files. The default behavior is reporting through terminal output only. Text, JSON and HTML files are automatically generated when running an assessment against a supported build tool, such as Maven for Java.

Flat Text File

You can instruct Adversa SDK Tools to report identified vulnerabilities via a flat text file using the --report switch. The following example saves all discovered vulnerabilities into a flat text file called vulns.txt.

$ adversa assess --sdk jvm --report vulns.txt -- mvn verify
JavaScript Object Notation (JSON) File

You can instruct Adversa SDK Tools to report identified vulnerabilities via a JSON file using the --report switch. The following example saves all discovered vulnerabilities into a JSON file called vulns.json.

$ adversa assess --sdk jvm --report vulns.json -- mvn verify
Hypertext Markup Language (HTML) File

You can instruct Adversa SDK Tools to report identified vulnerabilities via a HTML file using the --report switch. The following example saves all discovered vulnerabilities into a HTML file called vulns.html. Note that the optional --app switch is used to provide an application name of myapp to be rendered within the report.

$ adversa assess --app myapp --sdk jvm --report vulns.html -- mvn verify
Multiple Report Formats

You can instruct Adversa SDK Tools to generate multiple report formats through the use of a comma (,) delimiter in the --report switch. The following example generates a JSON file and a HTML file of all identified vulnerabilities. Note that the optional --app switch is used to provide an application name of myapp to be rendered within the report.

$ adversa assess --app myapp --sdk jvm --report vulns.json,vulns.html -- mvn verify

Licensing

Overview

Adversa SDK Tools supports both evaluation and commercial variants of licensing. The evaluation license does not expire but will only test for SQL Injection, Cross-Site Scripting and XML External Entities. Default installations of Adversa SDK Tools will be limited to an evaluation license.

A commercial license will provide access to the full suite of security tests as described in the knowledgebase as well as the ability to break builds within CI/CD pipeline(s). You may purchase a commercial license online.

Installation

License keys are of the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX and are emailed to the buyer upon purchase. This license key can be installed by running the following command in your terminal.

$ adversa license --install [key]

You should see output similar to the following if the installation was successful.

INFO adversa_sdk_tools checking for available updates
INFO adversa_sdk_tools installing license key [redacted]
INFO adversa_sdk_tools::license valid (kind:Business,users:30)
INFO adversa_sdk_tools operation succeeded
Verification

The status of an installed license can be verified by running the following command in your terminal.

$ adversa license --verify

You should see output similar to the following if the installation was successful.

INFO adversa_sdk_tools checking for available updates
INFO adversa_sdk_tools verifying installed license key
INFO adversa_sdk_tools::license valid (kind:Business,users:30)
INFO adversa_sdk_tools operation succeeded