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 itself, especially its [design specification](https://github.com/Arachni/arachni-rpc/wiki).
### Protocol
To provide functional examples of RPC interaction, I'll be using the
[pure Ruby client implementation](https://github.com/Arachni/arachni-rpc-pure)
of the Arachni-RPC protocol.
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)).
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 protocol is as simple as possible, utilizing OpenSSL sockets and very simple messages
to facilitate communication.
The only clarification required is about obtaining an Instance and maybe a couple
of examples to show you what controlling an Instance would look like.
### Serialization
1. [Connect to an Arachni RPC Dispatch server](#dispatcher-connect)
2. [Request an Arachni instance](#dispatcher-dispatch)
3. [Connect to the Instance](#instance-connect)
4. [Talking to the service handler](#instance-service)
The Arachni Framework provides its own serializer to the Arachni-RPC library.
It is essence using [MessagePack](http://msgpack.org/) with the addition of Zlib
compression when messages reach a certain size.
### 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.
```
gem install arachni-rpc-pure
```
The only clarification required is about obtaining an Instance, by following these 3 simple steps:
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 - Web Application Security Scanner Framework v0.4.2
Arachni - Web Application Security Scanner Framework v1.0
Author: Tasos "Zapotek" Laskos <[email protected]>
(With the support of the community and the Arachni Team.)
......@@ -39,86 +37,57 @@ Arachni - Web Application Security Scanner Framework v0.4.2
Documentation: http://arachni-scanner.com/wiki
Arachni - Web Application Security Scanner Framework v0.4.2
Author: Tasos "Zapotek" Laskos <[email protected]>
(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...]
I, [2014-08-03T19:28:31.867294 #48953] INFO -- System: RPC Server started.
I, [2014-08-03T19:28:31.867399 #48953] INFO -- System: Listening on 127.0.0.1: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
require 'arachni/rpc/pure'
# Pay no attention to this, it just starts the system that manages network
# connections in the background
Arachni::Reactor.global.run_in_thread
dispatcher = Arachni::RPC::Pure::Client.new(
host: 'localhost',
port: 7331
dispatcher = Arachni::RPC::Client::Dispatcher.new(
Arachni::Options.instance,
'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.
instance_info = dispatcher.call( 'dispatcher.dispatch' )
# =>
# {
# "token" => "bb5c94d2bd298cecf9da52421c0c0b71",
# "pid" => 26550,
# "port" => 62039,
# "url" => "localhost:62039",
# "owner" => "unknown",
# "birthdate" => 2013-03-30 04:34:26 +0200,
# "starttime" => 2013-03-30 04:36:24 +0200,
# "helpers" => {}
# }
ap instance_info = dispatcher.dispatch
# {
# "token" => "3edd7d8e9e4c717d364854e149ecd43c",
# "pid" => 48956,
# "port" => 24725,
# "url" => "127.0.0.1:24725",
# "owner" => "unknown",
# "birthdate" => "2014-08-03 19:28:31 +0300",
# "starttime" => "2014-08-03 19:50:48 +0300",
# "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::Pure::Client.new(
host: host,
port: port,
token: instance_info['token']
```
instance = Arachni::RPC::Client::Instance.new(
Arachni::Options.instance,
instance_info['url'],
instance_info['token']
)
# Makes it easier to perform RPC calls, allows calling `service.method_name`
# instead of `instance.call( 'service.method_name' )`.
service = Arachni::RPC::RemoteObjectMapper.new( instance, 'service' )
ap instance.service.alive?
# => true
```
**In order to successfully authenticate yourself to the instance don't forget
to include the authentication token.**
### <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
```
to include the authentication token.**
\ No newline at end of file