-
-
Notifications
You must be signed in to change notification settings - Fork 897
API Documentation
This page contains every attribute / method available to objects in AutoRecon, which is useful if you are writing plugins.
Target objects are created by AutoRecon from the list of targets given by the user. They are passed to PortScan plugins for scanning.
The address attribute returns a string representation of the target address in the form provided by the user (e.g. "127.0.0.1", "example.com"). Note that despite the name, this may not necessarily be an IP address.
The basedir attribute returns a string representation of the full (absolute) path to the target's results directory (e.g. /home/kali/results/127.0.0.1). No trailing slash is used.
The ip attribute returns a string representation of the target IP address (e.g. "127.0.0.1"). If a hostname was provided, AutoRecon will resolve the hostname to an IP address (first trying IPv4, then IPv6).
The ipversion attribute returns either "IPv4" or "IPv6", depending on the version of the target's IP address.
The ports attribute returns a dictionary containing two keys: 'tcp' and 'udp'. These point to a string representation of a port list that is compatible with the -p argument in Nmap.
The reportdir attribute returns a string representation of the full (absolute) path to the target's report directory (e.g. /home/kali/results/127.0.0.1/report). No trailing slash is used.
The scandir attribute returns a string representation of the full (absolute) path to the target's scans directory (e.g. /home/kali/results/127.0.0.1/scans). No trailing slash is used.
The type attribute returns either "ip" or "hostname", depending on whether the target address is an IP (either IPv4 or IPv6) or a hostname.
The add_service method can be used by a PortScan plugin to report a new service to AutoRecon at any point during the plugin's run. The service argument must be a valid Service object. This method returns None.
The execute method can be used by a PortScan plugin to execute a command in a /bin/bash shell. The cmd argument should be a string representation of the command you wish to execute. The following markers can be used within the string, and will get automatically converted to their correct values by AutoRecon:
-
{address}- The address of the target (e.g. 127.0.0.1, ::1, example.com). -
{addressv6}- Despite its name, this still represents the address of the target if it is IPv4 or a hostname. However, an IPv6 address will be surrounded with square brackets (e.g. [::1]) which is a common format for several tools. -
{ipaddress}- The IP address of the target (e.g. 127.0.0.1, ::1). If the target is a hostname, the resolved IP will be used. -
{ipaddressv6}- Despite its name, this still represents the IP address of the target if it is IPv4. However, an IPv6 address will be surrounded with square brackets (e.g. [::1]) which is a common format for several tools. If the target is a hostname, the resolved IP will be used. -
{nmap_extra}- Extra nmap options provided by the user at runtime. Defaults to: -vv --reason -Pn -
{scandir}- The full path to the target's scans directory (e.g. /home/kali/results/127.0.0.1/scans)
The optional blocking argument can be used to make the execute method return immediately, rather than waiting until the command has finished. This is useful if you want to process lines of output live. However, if you do this, you should always run the following command on the process object before returning:
await process.wait()The optional outfile and errfile arguments can be used to specify filenames to save stdout and stderr to respectively. Note that only the filename is required (e.g. "scan_output.txt", as the scandir path will be prepended.
This method returns a Process object, a CommandStreamReader object for stdout, and a CommandStreamReader object for stderr.
The extract_service method can be used by a PortScan plugin to extract a service from a provided string, using either AutoRecon's default regular expression (which works on Nmap output), or using a provided regular expression. The line argument should be the string you want to extract a service from. The optional regex argument can be used to provide a regular expression.
If a regular expression is provided, it must contain 3 named groups: port, protocol, and service which match the port (e.g. 80), protocol (e.g. TCP), and service name (e.g. http) respectively. As an example, the following regular expression is used by AutoRecon to extract services from Nmap output:
^(?P<port>\d+)\/(?P<protocol>(tcp|udp))(.*)open(\s*)(?P<service>[\w\-\/]+)(\s*)(.*)$
This method returns either a Service object (if the regular expression matched) or None (if it did not).
The extract_services method can be used by a PortScan plugin to extract multiple services from a provided CommandStreamReader, such as stdout, using either AutoRecon's default regular expression (which works on Nmap output), or using a provided regular expression. The stream argument should be a valid CommandStreamReader object, which is returned as part of the execute() method. The optional regex argument can be used to provide a regular expression.
If a regular expression is provided, it must contain 3 named groups: port, protocol, and service which match the port (e.g. 80), protocol (e.g. TCP), and service name (e.g. http) respectively. As an example, the following regular expression is used by AutoRecon to extract services from Nmap output:
^(?P<port>\d+)\/(?P<protocol>(tcp|udp))(.*)open(\s*)(?P<service>[\w\-\/]+)(\s*)(.*)$
This method returns either a list of Service objects (if the regular expression matched) or an empty list (if it did not).
Service objects are created by AutoRecon from the list of services reported by PortScan plugins. They are passed to ServiceScan plugins for scanning.
The name attribute returns a string representation of the name of the service (e.g. 'http').
The port attribute returns an integer representation of the port that the service is running on (e.g. 80).
The protocol attribute returns a lowercase string representation of the protocol that the service is using (e.g. 'tcp').
The secure attribute returns a boolean representation of whether or not the service is running over SSL/TLS.
The target attribute returns the Target object to which this Service object belongs. From this object you can get to any of the Target object's attributes if needed.
The add_manual_commands method can be used by ServiceScan plugins to add manual commands. A valid description must be used, and the commands argument can be a string or a list of strings.
The add_manual_command method is an alias for add_manual_commands and works the same way.
The execute method can be used by a ServiceScan plugin to execute a command in a /bin/bash shell. The cmd argument should be a string representation of the command you wish to execute. The following markers can be used within the string, and will get automatically converted to their correct values by AutoRecon:
-
{address}- The address of the target (e.g. 127.0.0.1, ::1, example.com). -
{addressv6}- Despite its name, this still represents the address of the target if it is IPv4 or a hostname. However, an IPv6 address will be surrounded with square brackets (e.g. [::1]) which is a common format for several tools. -
{ipaddress}- The IP address of the target (e.g. 127.0.0.1, ::1). If the target is a hostname, the resolved IP will be used. -
{ipaddressv6}- Despite its name, this still represents the IP address of the target if it is IPv4. However, an IPv6 address will be surrounded with square brackets (e.g. [::1]) which is a common format for several tools. If the target is a hostname, the resolved IP will be used. -
{http_scheme}- A special marker which is either 'https' or 'http' depending on whether the service is secure or not. -
{name}- The name of the service (e.g. 'http') -
{nmap_extra}- Extra nmap options provided by the user at runtime. Defaults to: -vv --reason -Pn -
{port}- The port that the service is running on (e.g. 80) -
{protocol}- The protocol that the service is using (e.g. 'tcp') -
{scandir}- The full path to the target's scans directory (e.g. /home/kali/results/127.0.0.1/scans)
The optional blocking argument can be used to make the execute method return immediately, rather than waiting until the command has finished. This is useful if you want to process lines of output live. However, if you do this, you should always run the following command on the process object before returning:
await process.wait()The optional outfile and errfile arguments can be used to specify filenames to save stdout and stderr to respectively. Note that only the filename is required (e.g. "scan_output.txt", as the scandir path will be prepended.
The optional future_outfile argument can be used to specify a future filename for the command, if you don't want the execute method to write to one immediately, but the plugin will eventually. This is needed for Report plugins to include results.
This method returns a Process object, a CommandStreamReader object for stdout, and a CommandStreamReader object for stderr.
The full_tag method returns a string representation of the service protocol, port, name, and whether it is secure, separated by forward slashes (e.g. tcp/80/http/insecure)
The tag method returns a string representation of the service protocol, port, and name, separated by forward slashes (e.g. tcp/80/http)
The readline method returns a single line from the CommandStream, or None if the stream has ended. This method will block until it can return something.
The readlines method returns all lines from the CommandStream, or an empty list if the stream has ended. This method will block until it can return something.
The following attributes and methods are available to both PortScan and ServiceScan plugins.
The description attribute is optional, but can be set to a string describing the purpose of the plugin. It is only used when plugins are listed using -l / --list.
The disabled attribute is a quick way to disable your plugin. Setting it to True means AutoRecon will not use it.
The name attribute should be set to the name of the plugin (e.g. 'Nmap HTTP'). Simple is better. Must be unique.
The priority attribute is optional, and by default will be 1. If set, it adjusts the priority of the plugin in the run sequence. A lower number means the plugin will be run before higher numbers. Negative and decimals are allowed.
The slug attribute is optional, as AutoRecon will generate a slug based on the name (e.g. 'Nmap HTTP' -> 'nmap-http'). If you don't like your slug, you can override it using this attribute. Simple is better. Must be unique.
The tags attribute is a list of tags that apply to the plugin. By default, the list is ['default']. If you want your plugin to run by default, you must include 'default' in the list if you override it.
The add_option method sets a command-line option for the plugin to use, where the value set to the option is stored if the option is used. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The default argument is optional, but if set, will return if the user does not specify the command-line option. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Command Line: --foo.bar=baz
Resulting Value: baz (string)
The add_constant_option method sets a command-line option for the plugin to use, where the value set to the const argument is stored if the option is used. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The default argument is optional, but if set, will return if the user does not specify the command-line option. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Code: add_constant_option("bar", "baz")
Command Line: --foo.bar
Resulting Value: baz (string)
The add_true_option method sets a command-line option for the plugin to use, where the boolean True is stored if the option is used. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Command Line: --foo.bar
Resulting Value: True (boolean)
The add_false_option method sets a command-line option for the plugin to use, where the boolean False is stored if the option is used. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Command Line: --foo.bar
Resulting Value: False (boolean)
The add_list_option method sets a command-line option for the plugin to use, where multiple space separated values are stored in a list is stored if the option is used. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Command Line: --foo.bar baz1 baz2 baz3
Resulting Value: ["baz1", "baz2", "baz3"] (list of strings)
The add_choice_option method sets a command-line option for the plugin to use, where the value set to the option is stored if the option is used, provided the value is within a predefined set of valid values. The name argument is used as part of the command-line option. For example, if a plugin called "Foo" added an option with the name "bar", the command-line option would be --foo.bar. The choices argument is a list of valid values the user can choose from. The help argument is also optional, but recommended to let users know what the option is to be used for.
This method should only be used in the configure() method of a plugin.
Example
Code: add_choice_option("bar", ["baz1", "baz2", "baz3"])
Command Line: --foo.bar baz2
Resulting Value: baz2 (string)
The get_option method is used to retrieve the value of an option (either set by the user or the default) that the plugin has previously configured. The name argument should be the same value as the name argument of the original option. In the event that an option was defined without a default value, the optional default argument can be set to a default value of your choice.
This method should only be used in the run() coroutine of a plugin.
The get_global_option method is used to retrieve the value of a global option (either set by the user or the default). The name argument should be the same value as the name argument of the global option. The optional default argument can be set to a default value of your choice.
This method can be used in the run() coroutine and the manual() method of a plugin.
The get_global_option method is an alias for the get_global_option method.
The add_pattern method is used to add a regex pattern to search for in any lines of command output generated by the plugin. An optional description argument can be used to specify the message which is output if the pattern matches (if no description argument is entered, the full match will be output instead). The description string can include special markers which will be replaced by pattern matches when the description is output:
- The
{match}marker will be replaced by the entire portion of command output that matches the regex. - The
{match#}markers, where # is a positive non-zero integer will be replaced by the match group with the same number. Correct usage of these markers requires some knowledge of match groups in regex.
This method should only be used in the configure() method of a plugin.
Example
Consider a plugin related to HTTP, where potential command output could contain response headers. It may be useful to match the Server header, as this often contains version information about the web server.
The following code can be used in the configure() method of the plugin:
self.add_pattern('Server: ([^\n]+)', description='HTTP Server Found: {match1}')The pattern Server: ([^\n]+) will match lines containing the string "Server: ", followed by any number of characters until a newline is encountered. The parentheses around [^\n]+ create a match group for that part of the pattern. Since this is the first group, it has a group number of 1.
The description HTTP Server Found: {match1} will output the string "HTTP Server Found: ", followed by only the portion of the match contained within group 1.
If the pattern matched the following command output:
Server: Apache/2.4.41 (Ubuntu)
The description output by AutoRecon would be:
HTTP Server Found: Apache/2.4.41 (Ubuntu)
Note that the "Server: " portion of the pattern is not present, despite being matched, because a group was used. If you want the entire match, you would need to change the description to HTTP Server Found: {match}, which would result in the following output by AutoRecon:
HTTP Server Found: Server: Apache/2.4.41 (Ubuntu)
Regex match groups can be difficult to grasp, but can be very powerful. They are numbered from left to right, including subgroups (groups within a group). I won't attempt to explain this in full detail here, however I will give the following example:
The pattern Example: ((foo) (bar)) (baz) contains 4 match groups. The first matches the entire string "foo bar", the second matches just the string "foo", the third matches just the string "bar", and the fourth matches the string "baz".