Created API Documentation (markdown)

API-Documentation.md

@@ -0,0 +1,59 @@
+# API Documentation
+
+This page contains every attribute / method available to objects in AutoRecon, which is useful if you are writing plugins.
+
+## Target
+
+Target objects are created by AutoRecon from the list of targets given by the user. They are passed to PortScan plugins for scanning.
+
+### Attributes
+
+#### address
+The `address` attribute returns a string representation of the target address (e.g. "127.0.0.1").
+
+#### basedir
+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.
+
+#### reportdir
+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.
+
+#### scandir
+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.
+
+### Methods
+
+#### add_service(service)
+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.
+
+#### execute(cmd, blocking=True, outfile=None, errfile=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)
+* {scandir} - The full path to the target's scans directory (e.g. /home/kali/results/127.0.0.1/scans)
+* {nmap_extra} - Extra nmap options provided by the user at runtime. Defaults to: -vv --reason -Pn
+
+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.
+
+#### extract_service(line, regex=None)
+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).
+
+#### extract_services(stream, regex=None)
+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).