{"id":100,"date":"2008-04-05T20:24:37","date_gmt":"2008-04-05T20:24:37","guid":{"rendered":"http:\/\/pentestmonkey.net\/?p=100"},"modified":"2011-08-20T15:49:08","modified_gmt":"2011-08-20T15:49:08","slug":"run-test-api","status":"publish","type":"post","link":"https:\/\/pentestmonkey.net\/yaptest\/using\/run-test-api","title":{"rendered":"The Yaptest run_test API"},"content":{"rendered":"<p>This page documents how to use the run_test API from your own home-brew <a href=\"http:\/\/pentestmonkey.net\/projects\/yaptest\/yaptest-overview\/\">yaptest<\/a> scripts.<\/p>\n<p>&nbsp;<\/p>\n<p><!--more--><\/p>\n<h2>Examples<\/h2>\n<p>Before we dig into the details of how to use the API, it&#8217;s worth poining out that there are lots of examples in the <a href=\"http:\/\/pentestmonkey.net\/projects\/yaptest\/yaptest-installation\/\">yaptest tar ball<\/a>.\u00a0 This documentation is provided for completeness, not because I think it&#8217;s particularly needed.<\/p>\n<p>Most of the pentesters I&#8217;ve seen use Yaptest have been able to copy existing yaptest scripts and modify them to do their bidding.\u00a0 The following scripts demonstrate different capabilities of yaptest, so pick one that demonstrates the feature you&#8217;re interested in, copy it, then modify it:<\/p>\n<ul>\n<li>yaptest-nmap-udp.pl demonstrates how to run a command against every IP address in the database, and to provide that IP as an option to the tool (in this can nmap -sU).<\/li>\n<li>yaptest-nbtscan.pl demonstrates how to run a command against every IP address in the database, and to provide a file of IP addresses as an option to the tool (in this can nbtscan).<\/li>\n<li>yaptest-tftp.pl demonstrates how to run a command against particular UDP ports (in this case 69\/UDP).<\/li>\n<li>yaptest-showmount.pl demonstrates how to run a tool against all hosts who have a certain string contained in their &#8216;rpcinfo -p&#8217; output (in this case run showmount against hosts which have &#8216;100003&#8217; in their rpcinfo output).<\/li>\n<li>yaptest-nikto.pl demonstrates how to run a tool against ports based on nmap&#8217;s fingerprint of that port (in this case run nikto on ports that nmap thinks are HTTP).<\/li>\n<li>yaptest-amap-tcp.pl demonstrates how to run a tool against all TCP ports.<\/li>\n<li>yaptest-httprint.pl demonstrates how to run a tool against only SSL \/ non-SSL ports.<\/li>\n<li>yaptest-tnscmd.pl demonstrates how to set a hard-timeout that kills a script after a certain period of time.<\/li>\n<li>yaptest-oscanner.pl demonstrates how to set a softer timeout that only kills a script if it&#8217;s produced no output for a certain period of time.<\/li>\n<li>yaptest-smtpscan.pl demonstrates how to kill a script if it produces too many lines of output.<\/li>\n<li>yaptest-nxscan.pl demonstrates how to run 20 copies of a script in parallel to speed up testing.<\/li>\n<\/ul>\n<h2>API Documentation<\/h2>\n<p>The run_test API is the main (and recommended) way of running external tools against hosts in the yaptest database.<\/p>\n<pre>my $y = yaptest-&gt;new();\r\n$y-&gt;run_test(\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 command =&gt; \"external-program -h ::IP:: -p ::PORT::\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 filter =&gt; { filter_key =&gt; filter_value, filter_key2 =&gt; filter_value2 },\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 next_parameter_key =&gt; next_parameter_value,\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ...\r\n);<\/pre>\n<p>The follows sections discuss each of the parameters that may be passed via the run_test API.<\/p>\n<h3>Command<\/h3>\n<p>The command parameter is mandatory &#8211; the only mandatory parameter in fact.\u00a0 The value of &#8220;command&#8221; must be a string that contains a template for the command you want to run:<\/p>\n<pre>\u00a0\u00a0\u00a0 command =&gt; \"mycommand -h ::IP:: -p ::PORT::\"<\/pre>\n<p>The command template if formed by writing the exact command you&#8217;d normally run, but replacing certain parts of the command this a special mark-up.\u00a0 Replace:<\/p>\n<ul>\n<li>The target IP address with ::IP::<\/li>\n<li>The target port (if any) with ::PORT::<\/li>\n<li>A file of target IP addresses with ::IPFILE::<\/li>\n<li>A list of comma-separated target ports with ::PORTLIST::<\/li>\n<li>A list of space-separated target ports with ::PORTLIST-SPACE::<\/li>\n<li>A file of target ports with ::PORTFILE::<\/li>\n<\/ul>\n<p>So if you&#8217;d normally run your nmap scan like this:<\/p>\n<pre>nmap -sS 10.0.0.1<\/pre>\n<p>your template would be:<\/p>\n<pre>nmap -sS ::IP::<\/pre>\n<p>However, if you run your nmap scans like this:<\/p>\n<pre>nmap -sS 10.0.0.1 -iL ips.txt<\/pre>\n<p>your template would be:<\/p>\n<pre>nmap -sS 10.0.0.1 -iL ::IPFILE::<\/pre>\n<p>If you run nikto like this:<\/p>\n<pre>nikto -h 10.0.0.1 -p 80<\/pre>\n<p>your template would be:<\/p>\n<pre>nikto -h ::IP:: -p::PORT::<\/pre>\n<p>&#8220;But exactly what are ::IP:: and ::PORT:: going to be replaced with?&#8221; I hear you ask.\u00a0 Check out the &#8220;Filter&#8221; parameter below&#8230;<\/p>\n<h3>Filter<\/h3>\n<p>This option lets you restrict the hosts \/ ports your external tool with run against.\u00a0 It is not mandatory.\u00a0 If omitted, your external tool will be run against everything.<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { key =&gt; value, key =&gt; value}<\/pre>\n<p>The comma above is interpretted as AND, i.e. only hosts \/ ports matching ALL of the supplied key =&gt; value pairs will be selected by the filter.\u00a0 Read on and it&#8217;ll all make sense&#8230;<\/p>\n<p>Possible &#8220;key&#8221;s are:<\/p>\n<p><strong>port<\/strong>.\u00a0 This lets you run your tool only against specific ports.\u00a0 The &#8220;value&#8221; is either a port number or an array of port numbers:<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { port =&gt; 22 }<\/pre>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { port =&gt; [80, 443, 8080] }<\/pre>\n<p>Note that you can only have one filter line and the commas above are obviously interpretted as OR.\u00a0 Any mathing port is selected by the filter.<\/p>\n<p><strong>transport_protocol<\/strong>.\u00a0 This lets you run your tool only against specific transport protocols.\u00a0 The value is a string &#8220;TCP&#8221; or &#8220;UDP&#8221;.\u00a0 It&#8217;s commonly used with &#8216;port&#8217;:<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { port =&gt; 22, transport_protocol =&gt; 'TCP' }<\/pre>\n<p><strong>port_info<\/strong>.\u00a0 This lets you run your tool only against ports that have certain attributes.\u00a0 These attributes are stored in yaptest&#8217;s port_info table.\u00a0 The &#8220;value&#8221; is a string.\u00a0 Typically you&#8217;ll use this run a tool against all ports that nmap has identified as HTTP (or SSH or oracle-tns or whatever).<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { port_info =&gt; \"nmap_service_name = http\" }<\/pre>\n<p><strong>ssl<\/strong>.\u00a0 This lets you run your tool only SSL ports.\u00a0 The &#8220;value&#8221; is 0 or 1.<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { port_info =&gt; \"nmap_service_name = http\", ssl =&gt; 0 }<\/pre>\n<p><strong>ip<\/strong>.\u00a0 This lets you run your tool only against a specific IP address.\u00a0 The &#8220;value&#8221; is a string.\u00a0 I don&#8217;t know why you&#8217;d use this feature.\u00a0 I never have.<\/p>\n<pre>\u00a0\u00a0\u00a0 filter =&gt; { ip =&gt; \"127.0.0.1\" }<\/pre>\n<h3>Output File<\/h3>\n<p>This parameter tells yaptest where to store the output from the external tool.\u00a0 It is not mandatory.\u00a0 It defaults to a name based on the tool name.\u00a0 If you were to run something like this:<\/p>\n<pre>\u00a0\u00a0\u00a0 command =&gt; \"ping -c 1 ::IP::\"<\/pre>\n<p>The output file would be called &#8220;ping.out&#8221;. Next time you run it, the output file will not be overwritten, it will be called &#8220;ping.out.1&#8221;, then &#8220;ping.out.2&#8221;, etc.<\/p>\n<p>My output files are not going to be particularly self-documenting are they? Can&#8217;t I store the target IP in the file name? Of course you can:<\/p>\n<pre>\u00a0\u00a0\u00a0 output_file =&gt; \"ping-::IP::.out\"<\/pre>\n<p>You can use the same mark-up as for &#8220;command&#8221;, but some doesn&#8217;t make sense (like ::IPFILE::). ::IP:: and ::PORT:: are typically the only ones you&#8217;ll use in output file names.<\/p>\n<h3>Parallel Processes<\/h3>\n<p>Yaptest can fork off several copies of the external tool to speed up testing.\u00a0 It is not mandatory and defaults to 1.<\/p>\n<pre>\u00a0\u00a0\u00a0 parallel_processes =&gt; 5<\/pre>\n<p>This option is useful for lots of tools, for example on an internal network if you nikto on each website in turn you may never complete your test.\u00a0 You probably want to run (say) 5 in parallel.<\/p>\n<h3>Timeout<\/h3>\n<p>Yaptest can kill external tools if they take too long.\u00a0 This option is not mandatory.\u00a0 The default is no timeout &#8211; tools can run forever.<\/p>\n<p>Some tools misbehave by just hanging forever.\u00a0 You don&#8217;t want this delaying the rest of your test, so specify a timeout in seconds like this:<\/p>\n<pre>\u00a0\u00a0\u00a0 timeout =&gt; 60<\/pre>\n<h3>Inactivity Timeout<\/h3>\n<p>If the &#8220;timeout&#8221; option above seems a little too harsh, this option may suit you better.\u00a0 It kills external tools only if they produce no output for a certain period of time:<\/p>\n<pre>\u00a0\u00a0\u00a0 inactivity_timeout =&gt; 60<\/pre>\n<p>If you ran a command like &#8220;ping 127.0.0.1&#8221; that kept producing a line of output each second forever, yaptest would <em>never <\/em>kill the external tool. Sometimes this is what you want, sometimes it isn&#8217;t. Choose carefully.<\/p>\n<h3>Maximum Lines<\/h3>\n<p>Yaptest is able to kill your external tools if they produce too much output (e.g. 1000 lines of &#8220;connection refused&#8221;).\u00a0 By default yaptest will not kill tools that produce a lot of output.<\/p>\n<pre>\u00a0\u00a0\u00a0 max_lines =&gt; 4000<\/pre>\n<h3>Parser<\/h3>\n<p>This lets you call a parsing script automatically on the output file created by yaptest.\u00a0 The output file contains output of the external tool an may contain information that needs to be parsed into the database.\u00a0 It&#8217;s not mandatory, though.\u00a0 If you have a parser for your tool&#8217;s output, you should use the auto-parse feature.\u00a0 If you don&#8217;t, then don&#8217;t worry.<\/p>\n<pre>\u00a0\u00a0\u00a0 parser =&gt; \"yaptest-parse-nbtscan.pl\"<\/pre>\n<h3><\/h3>\n<p>&nbsp;<\/p>\n<p>&nbsp;<\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This page documents how to use the run_test API from your own home-brew yaptest scripts. &nbsp;<\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[10],"tags":[69],"_links":{"self":[{"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/posts\/100"}],"collection":[{"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/comments?post=100"}],"version-history":[{"count":1,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/posts\/100\/revisions"}],"predecessor-version":[{"id":370,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/posts\/100\/revisions\/370"}],"wp:attachment":[{"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/media?parent=100"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/categories?post=100"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pentestmonkey.net\/wp-json\/wp\/v2\/tags?post=100"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}