Skip to content
GitLab

RPC API · Changes

Page history
Updated RPC-API (markdown) authored by Tasos Laskos's avatar Tasos Laskos
Hide whitespace changes
Inline Side-by-side
guides/developer/RPC-API.md
View page @ 8e073653
## Version 0.4.3 ## Version 1.0
First of all, you should take a look at the [Arachni-RPC](https://github.com/Arachni/arachni-rpc) ### Protocol
protocol itself, especially its [design specification](https://github.com/Arachni/arachni-rpc/wiki).
To provide functional examples of RPC interaction, I'll be using the Arachni uses its own RPC implementation, provided by [Arachni-RPC](https://github.com/Arachni/arachni-rpc) ([design specification](https://github.com/Arachni/arachni-rpc/wiki)).
[pure Ruby client implementation](https://github.com/Arachni/arachni-rpc-pure)
of the Arachni-RPC protocol.
The [RPC API of the Instances](http://rubydoc.info/github/Arachni/arachni/Arachni/RPC/Server/Instance) The protocol is as simple as possible, utilizing OpenSSL sockets and very simple messages
is well documented and contains all the info you'll need. to facilitate communication.
The only clarification required is about obtaining an Instance and maybe a couple ### Serialization
of examples to show you what controlling an Instance would look like.
1. [Connect to an Arachni RPC Dispatch server](#dispatcher-connect) The Arachni Framework provides its own serializer to the Arachni-RPC library.
2. [Request an Arachni instance](#dispatcher-dispatch) It is essence using [MessagePack](http://msgpack.org/) with the addition of Zlib
3. [Connect to the Instance](#instance-connect) compression when messages reach a certain size.
4. [Talking to the service handler](#instance-service)
### Setting up the test environment ### Communicating with Arachni
First of all, install the Arachni-RPC Pure client: The [RPC API of the Instances](http://rubydoc.info/github/Arachni/arachni/Arachni/RPC/Server/Instance)
is well documented and contains all the info you'll need.
``` The only clarification required is about obtaining an Instance, by following these 3 simple steps:
gem install arachni-rpc-pure
``` 1. [Connect to a Dispatcher](#dispatcher-connect)
2. [Request an Instance](#dispatcher-dispatch)
3. [Connect to an Instance](#instance-connect)
Now, we'll need to run an Arachni RPC Dispatcher to have something to work and play with. First of all, we need to run a Dispatcher:
``` ```
$ arachni_rpcd $ arachni_rpcd
Arachni - Web Application Security Scanner Framework v0.4.2 Arachni - Web Application Security Scanner Framework v1.0
Author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com> Author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
(With the support of the community and the Arachni Team.) (With the support of the community and the Arachni Team.)
...@@ -39,86 +37,57 @@ Arachni - Web Application Security Scanner Framework v0.4.2 ...@@ -39,86 +37,57 @@ Arachni - Web Application Security Scanner Framework v0.4.2
Documentation: http://arachni-scanner.com/wiki Documentation: http://arachni-scanner.com/wiki
Arachni - Web Application Security Scanner Framework v0.4.2 I, [2014-08-03T19:28:31.867294 #48953] INFO -- System: RPC Server started.
Author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com> I, [2014-08-03T19:28:31.867399 #48953] INFO -- System: Listening on 127.0.0.1:7331
(With the support of the community and the Arachni Team.)
Website: http://arachni-scanner.com
Documentation: http://arachni-scanner.com/wiki
I, [2012-08-28T05:29:39.412457 #23997] INFO -- System: RPC Server started.
I, [2012-08-28T05:29:39.412557 #23997] INFO -- System: Listening on localhost:1605
[...lots of similar output...]
``` ```
This is what happens when no options have been set; the default port is `7331`. This is what happens when no options have been set; the default port is `7331`.
### <a id="dispatcher-connect" href="#dispatcher-connect">Connect to an Arachni RPC Dispatch server</a> #### <a id="dispatcher-connect" href="#dispatcher-connect">Connecting to a Dispatcher</a>
```
require 'arachni'
require 'arachni/rpc/client'
```ruby # Pay no attention to this, it just starts the system that manages network
require 'arachni/rpc/pure' # connections in the background
Arachni::Reactor.global.run_in_thread
dispatcher = Arachni::RPC::Pure::Client.new( dispatcher = Arachni::RPC::Client::Dispatcher.new(
host: 'localhost', Arachni::Options.instance,
port: 7331 'localhost:7331'
) )
``` ```
### <a id="dispatcher-dispatch" href="#dispatcher-dispatch">Request an Arachni instance</a> #### <a id="dispatcher-dispatch" href="#dispatcher-dispatch">Requesting an Instance</a>
```ruby ```
# Request for an instance to be dispatched. # Request for an instance to be dispatched.
instance_info = dispatcher.call( 'dispatcher.dispatch' ) ap instance_info = dispatcher.dispatch
# => # {
# { # "token" => "3edd7d8e9e4c717d364854e149ecd43c",
# "token" => "bb5c94d2bd298cecf9da52421c0c0b71", # "pid" => 48956,
# "pid" => 26550, # "port" => 24725,
# "port" => 62039, # "url" => "127.0.0.1:24725",
# "url" => "localhost:62039", # "owner" => "unknown",
# "owner" => "unknown", # "birthdate" => "2014-08-03 19:28:31 +0300",
# "birthdate" => 2013-03-30 04:34:26 +0200, # "starttime" => "2014-08-03 19:50:48 +0300",
# "starttime" => 2013-03-30 04:36:24 +0200, # "helpers" => {}
# "helpers" => {} # }
# }
``` ```
### <a id="instance-connect" href="#instance-connect">Connect to the Arachni RPC instance</a> #### <a id="instance-connect" href="#instance-connect">Connecting to an Instance</a>
```ruby ```
host, port = instance_info['url'].split( ':' ) instance = Arachni::RPC::Client::Instance.new(
instance = Arachni::RPC::Pure::Client.new( Arachni::Options.instance,
host: host, instance_info['url'],
port: port, instance_info['token']
token: instance_info['token']
) )
# Makes it easier to perform RPC calls, allows calling `service.method_name` ap instance.service.alive?
# instead of `instance.call( 'service.method_name' )`. # => true
service = Arachni::RPC::RemoteObjectMapper.new( instance, 'service' )
``` ```
**In order to successfully authenticate yourself to the instance don't forget **In order to successfully authenticate yourself to the instance don't forget
to include the authentication token.** to include the authentication token.**
\ No newline at end of file
### <a id="instance-service" href="#instance-service">Talking to the service handler</a>
To make things easier, the [service](http://rubydoc.info/github/Arachni/arachni/Arachni/RPC/Server/Instance)
handler of the RPC Instance exposes a number of methods which provide the most
commonly used functionality.
That way, you won't have to talk directly to the more specialized, and often
more complicated, system components (like the Framework, Module manager, Plugin
manager, etc.).
Let's see how one would go about performing a few calls.
```ruby
service.list_modules
```
To call a server-side method with parameters you simply pass those parameters as usual:
```ruby
service.progress without: :stats
```