Usage, Parameters, and Output

Usage

Once you have a compiled JAR, run the program with:

java -jar attack-surface-detector-cli.jar <root-folder> [-flags]

If successful, you should see various output in the console regarding endpoints declared in the given code.

> java -jar attack-surface-detector-cli.jar "C:\.....\AltoroJ 3.1.1"
Beginning endpoint detection for 'C:\.....\AltoroJ 3.1.1'
Using framework=JSP
Generated 47 distinct endpoints with 26 variants for a total of 73 endpoints
[0] GET: /admin/admin.jsp (1 variants): PARAMETERS={}; FILE=/WebContent/admin/admin.jsp (lines '1'-'194')
[1] -- POST: /admin/admin.jsp (0 variants): PARAMETERS={}; FILE=/WebContent/admin/admin.jsp (lines '1'-'194')
[2] GET: /admin/feedbackReview.jsp (1 variants): PARAMETERS={}; FILE=/WebContent/admin/feedbackReview.jsp (lines '1'-'75')
[3] -- POST: /admin/feedbackReview.jsp (0 variants): PARAMETERS={}; FILE=/WebContent/admin/feedbackReview.jsp (lines '1'-'75')

...

-- DONE --
Generated 73 total endpoints
Generated 50 total parameters
To enable logging include the -debug argument

Saving to JSON

The detected endpoints can be serialized and stored in a JSON file. This is done using the -json and -output-file=... parameters:

> java -jar attack-surface-detector-cli.jar C:\...\SourceCode -json -output-file=C:\...\endpoints.json

This -json output uses a common object format for all endpoints generated. By default, these endpoints will not contain source code information. This can be included by adding the -include-source flag.

Options

<root-folder>

Runs endpoint detection on code location in the given folder path. (Required, unless -path-list-file=... is specified)

---

-defaultFramework=<framework>

Specifies the web framework used in the given code location. If undefined, the HAM module will attempt to detect the framework type automatically. Accepted values at time of writing are:

1. JSP (Java JSP and Servlets)
2. DOT_NET_MVC (ASP.NET MVC, Web API, ASP.NET Core)
3. DOT_NET_WEB_FORMS (ASP.NET Web Forms)
4. STRUTS
5. SPRING_MVC
6. RAILS (Ruby on Rails)
7. PYTHON (Django)

ASP.NET technologies are generally grouped under the DOT_NET_MVC identifier. This is incorrect, but will be preserved for now for backwards compatibility.

---

-debug

Enables DEBUG log messages.

---

-simple

Disables diagnostic messages that are usually output by the tool.

---

-path-list-file="/path/to/list.txt"

Runs endpoint detection on each code location specified in the given file list. An example can be found here.

---

-json

Outputs a simplified JSON-serialized version of the detected endpoints, intended for use by any JSON parser. It provides a consistent and simplified format for all generated endpoints. JSON generated does not include source code data.

If multiple projects are scanned at once, the JSON output will contain a single array of all endpoints from all scanned projects.

---

-include-source

When combined with -json, includes source code information for detected endpoints. This includes line number for the associated code and the file path of the source code (relative to the scanned project's root folder.)

---

-full-json

Outputs a complete JSON-serialized version of the detected endpoints, intended for deserialization by the threadfix-ham module. Endpoints are stored with framework-specific content, wrapped in an object indicating the framework type for that endpoint. All available source code information is included.

If multiple projects are scanned at once, the JSON output will contain a single array of all endpoints from all scanned projects.

Endpoints retrieved through this method should be deserialized via com.denimgroup.threadfix.framework.engine.full.EndpointSerialization.deserializeAll(..) from the threadfix-ham module.

---

-output-file=...

Specifies an output file that endpoints will be written to when using JSON serialization. This requires either -json or -simple-json to also be set, otherwise this flag has no effect.

---

-validation-server=http://localhost:1234/abc...

Specifies a base URL path that will be used and queried against to test all detected endpoints. Endpoints that return 404 will be marked as "failed" and listed in the terminal.

---

- validation-server-auth=<login-endpoint>;usename=foo;password=bar;...

Specifies how to authenticate against the server provided with -validation-server. Arguments are separated by semicolons ;. The first argument will be the endpoint to use for authentication. Subsequent arguments will be sent to the endpoint while authenticating.

The specified endpoint will be POSTed to, and the provided query parameters will be encoded as Form parameters. Result of authentication will be output in the console.

Any cookies found in the response will be attached to all subsequent requests during testing.

Debug Information

The console output can include various debug information at the end of a scan for validation. This typically looks like:

Got an absolute file path when a relative path was expected instead, for: GET,/^(?P<i18>[\w\-_]+)/^admin/^mypageextension/$,{}
Failed to validate serialization for at least one of these endpoints
251 endpoints were missing code start line
251 endpoints were missing code end line
0 endpoints had the same code start and end line
Generated 38 parameters
- 38/38 have their data type
- 0/38 have a list of accepted values
- 0/38 have their parameter type
--- UNKNOWN: 38

Endpoints without a line range will have their start and end lines set to -1. Parameters are associated with a name, data type, and parameter type, which are summarized at the end. The parameter types are:

• UNKNOWN - The parameter type could not be detected
• QUERY_STRING - A parameter stored in the URL of the request ie /index.php?query=value
• FORM_DATA - Any form-type data. Can also be used to store the body of a request
• PARAMETRIC_ENDPOINT - A parameter embedded in the URL, ie /books/{bookId}/order
• SESSION - A parameter stored as session data
• COOKIE - A parameter stored as a cookie
• FILES - A parameter for file uploads