Created PortScan Plugin (markdown)

PortScan-Plugin.md

@@ -0,0 +1,61 @@
+# PortScan Plugin
+
+The following is an example PortScan plugin:
+
+```python
+from autorecon import PortScan
+
+class QuickTCPPortScan(PortScan):
+
+    def __init__(self):
+        super().__init__()
+        self.name = "Top TCP Ports"
+        self.tags = ["default", "default-port-scan"]
+        self.priority = 0
+
+    async def run(self, target):
+        process, stdout, stderr = await target.execute('nmap {nmap_extra} -sV -sC --version-all -oN "{scandir}/_quick_tcp_nmap.txt" -oX "{scandir}/xml/_quick_tcp_nmap.xml" {address}')
+        services = await target.extract_services(stdout)
+        return services
+```
+
+Here is a breakdown:
+
+```python
+from autorecon import PortScan
+```
+
+This simply imports the PortScan class from AutoRecon, something that is required to write a valid PortScan plugin.
+
+```python
+class QuickTCPPortScan(PortScan):
+
+    def __init__(self):
+        super().__init__()
+        self.name = "Top TCP Ports"
+        self.tags = ["default", "default-port-scan"]
+        self.priority = 0
+```
+
+Each plugin is defined as a class. If you are familiar with object-oriented programming, you'll understand this. If not, just know that a class name ("QuickTCPPortScan" in this case) has to be unique. The parantheses after the classname tell AutoRecon that this is a PortScan plugin.
+
+Every plugin has a number of methods / functions that it must define. The first is the __init__ method, which must call `super().__init__()` before anything else.
+
+The last three lines define attributes of the plugin. Technically, only `self.name` is required. This is the name which AutoRecon will use when referring to the plugin in its output, and so should ideally be kept short. It should also be unique, but does not have to be the same as the class name.
+
+`self.tags` defines a list of tags that the plugin belongs to. By default, all plugins are tagged as "default" only, meaning the plugin will run if no tags are specified on the command line. If you override the tags list, you should include the "default" tag if you want the plugin to run by default.
+
+`self.priority` is a number which defaults to 1, and sets the order in which plugins are run. If you want a plugin to run before the others, set the priority attribute to a number less than 1 (negative numbers and decimals are allowed). Conversely, if you want a plugin to run after the others, set the priority attribute to a number greater than 1.
+
+```python
+    async def run(self, target):
+        process, stdout, stderr = await target.execute('nmap {nmap_extra} -sV -sC --version-all -oN "{scandir}/_quick_tcp_nmap.txt" -oX "{scandir}/xml/_quick_tcp_nmap.xml" {address}')
+        services = await target.extract_services(stdout)
+        return services
+```
+
+The "run" method is actually a coroutine, identified by the "async" keyword before the definition. This means it will run asynchronously (i.e. concurrently) with other methods. This method is passed a Target object via the "target" argument in the definition.
+
+Target objects have an "execute" method which can be used to execute commands on the underlying OS. As this method is asynchronous, it must be awaited using the "await" keyword. This method returns three things: a Process object, a custom CommandStreamReader which reads standard output, and a custom CommandStreamReader which reads standard error.
+
+For this example, you do not need to worry about the Process object or stderr. Instead, you can use the "extract_services" method of the Target object to generate a list of Service objects by giving it the "stdout" CommandStreamReader. The final line simply returns this list of Service objects back to AutoRecon for further processing.