Updated: 2011-08-12
This a continued project for RemoteSubmit v1.0 Beta, that works via SOAP instead of GET/POST-submissions like the old version. Hopefully this document is better than the old one at http://dnsbl.tornevall.org/?do=soapclient
Request access to SOAPSubmit at dnsbl@tornevall.org
SOAPSubmit allows remote submission of webspamming hosts, with username-authentication. It also allows trusted sites to remotely remove blacklisted ip-adresses automatically (by default, they can only remove their own submissions). The project also allows authenticated users to check the status on added hosts in the DNS Blacklist.
Report bugs or sign up for using RemoteSubmit via dnsbl@tornevall.org
See our example-client here!
A demo user is available for the testclient, as defined in the script. Username is demo, password is demo. Observe, that this username only have read-access.
Defined as constants in SOAPServer
1 - DNSBL_PERMISSION_DENIED
This documentation is based on the example that can be found at http://dnsbl.tornevall.org/soap/soapclient.php?do=viewsource
The current configuarion for a PHP-script should can look like the example below. Currently the soapsubmit-script are located at http://dnsbl.tornevall.org/soap/soapsubmit.php (use https if you want a secure link to the tool).
define('SUBMITURL', 'http://dnsbl.tornevall.org/soap/soapsubmit.php');
$soapconf = array
(
'location' => SUBMITURL,
'uri' => SUBMITURL,
'trace' => 0,
'exceptions' => 0,
'connection_timeout' => 0
);
If you're using authentication, you also need to define your username and password. The user demo currently has read-only access if needed.
class UserinfoClass
{
private $Username = "demo";
private $Password = "demo";
}
The SOAP-Client can log in to the soap-server without authentication (as described above). In such cases, only readonly functions are available. User authentication are sent with an object array and looks like this in a raw-dump:
[userinfo] => UserinfoClass Object
(
[Username:UserinfoClass:private] => demo
[Password:UserinfoClass:private] => demo
)
In PHP it could look like this:
class UserinfoClass
{
private $Username = "demo";
private $Password = "demo";
}
In this moment, response will return only if authentication fails.
[error] => Array
(
[code] => 1
[message] => NoAccess
)
When logging in successfully you'll get an array-response called Access of which usertype you logged in as:
Array (
[Version] => 2.0.1
[Features] => Array
(
[details] => 2.0.1
)
[Access] => Array
(
[You] => demo
[Read] => true
[Write] => false
)
)
The array definition above tells you that you logged in as demo, with Read-only permission. By doing this you may build a client that detects itself if it may read and write data to the blacklist server. You also get information about the current server-version. You should look at this side from time to time, just to be sure that you're not missing any new features.
All data sent to soapsubmit will return an array with “SubmitData”-confirmation. This is a kind of validity check so your client can confirm that the data sent to the server is the correct one when receiving the main result. It's a kind of traceback function. For example, it may look like this
[SubmitData] => Array
(
[check] => Array
(
[ip] => 79.133.196.124
)
)
IP-Checking can be made with readonly permission. For the moment, this function actually doesnt require authentication at all. Doing an ip-check requires a minimum amount of data, in a PHP-script:
$client = new SoapClient(null, $soapconf);
$result = $client->submit(null, array('check' => array('ip' => '79.133.196.124')));
The default return response in version 2.0.1 is a short one, so requesters can save bandwidth/load and contains the most important data about the ip-address:
[Response] => Array
(
[proxydb] => Array
(
[listed] => 1
)
[dnsdb] => Array
(
[listed] => 4
)
)
If the value of listed equals one in the proxydb-array, you know this is a blacklisted ip. Otherwise, it returns 0. There may also be a dnsbl-response - this value tells you how many times the ip appears live in the DNS. If you see a count of 4 in the response, it's probably listed both at opm.tornevall.org and dnsbl.tornevall.org.
If you want full details about the requested ip, add the variable “details” into the request. Like this:
$req = array('check' => $check, 'details'=>true);
Doing this will extend the response to the following (example):
[Response] => Array
(
[proxydb] => Array
(
[idx] => true
[ip] => 79.133.196.124
[message] =>
[timestamp] => 1312982514
[humantimestamp] => 2011-08-10 15:21:54
[addrtoname] => 79.133.196.124
[abuse] => true
[tor] => false
[announced] => true
[remote] => false
[proxyweb1] => false
)
[dnsdb] => Array
(
[0] => Array
(
[name] => 124.196.133.79.dnsbl.tornevall.org
[ttl] => 3600
[rdtype] => A
[rdata] => 127.0.0.67
[ip] => 79.133.196.124
)
[1] => Array
(
[name] => 124.196.133.79.dnsbl.tornevall.org
[ttl] => 3600
[rdtype] => TXT
[rdata] => Blocked - see http://dnsbl.tornevall.org
[ip] => 79.133.196.124
)
[2] => Array
(
[name] => 124.196.133.79.opm.tornevall.org
[ttl] => 3600
[rdtype] => A
[rdata] => 127.0.0.67
[ip] => 79.133.196.124
)
[3] => Array
(
[name] => 124.196.133.79.opm.tornevall.org
[ttl] => 3600
[rdtype] => TXT
[rdata] => Blocked - see http://dnsbl.tornevall.org
[ip] => 79.133.196.124
)
)
)
In this case you'll now see the full entries both in the proxydatabase and the live DNS. If the ip is not listed in the extended mode, you'll get empty arrays.
[Response] => Array
(
[proxydb] => Array
(
)
[dnsdb] => Array
(
)
)
But it's not over here. SOAPSubmit also tells you if the ip-address has been externally submitted. Beside the above information about a submitted ip, from the check-function, the server also returns - if the data exists - information from our remote-submit-database. This is an example of that:
[Response] => Array
(
[have_r_entry] => true
[r_entry_count] => 1
[r_ownership] => false
)
have_r_entry only means that our remote-submit-database contains entries matching the ip submitted to the checker. r_entry_count shows how many times the ip has been submitted. If this value is > 1 it probably have been resubmitted after deletion or so. r_ownership is quite interesting, since this value tells you if you have submitted the ip or if someone else did.
There is also another value that shows up if you are allowed to remove this ip-address if it wasnt your client that submitted it: delete_other_permission
This is the key feature for SOAPSubmit. Without it, you cannot add or remove ipaddresses from our DNS/Proxydatabase. Adding and removing hosts are quite easy. Start with an array:
$add = array(
'ip' => '127.0.0.100',
'username' => 'SpammerUser',
'mail' => 'spam@spam.ru'
);
This array is actually customized for stopforumspam, so if you don't have any use for it, you don't need to submit the username and mailaddress. The only value that is required for this to work is the ip-address. With the proper values added, you are ready to submit the ip:
$req = array('add' => $add);
$result = $client->submit($udata, $req);
Adding a ip-address may cause three different responses:
Those three responses are present like this, where you get confirmation on which ip has been added or updated::
[Response] => Array
(
[update] => Array
(
[ip] => 127.0.0.100
[updated] => true
)
)
… or which ip that has been inserted into the database:
[Response] => Array
(
[insert] => Array
(
[idx] => 225771
[ip] => 127.0.0.101
[username] => SpammerUser
[mail] => spam@spam.ru
)
)
The shown idx actually has no function anymore, and it only shows the position in the blacklist-database. If the ip is already added by someone else you'll get the short fail-message:
[Response] => Array
(
[update] => fail_on_ownership
)
Deletion is as simple as the insert was and in this case, you only need the ipaddress, so this could be put on one line:
$result = $client->submit($udata, array('delete' => array('ip' => '127.0.0.100')));
Three responses can be returned. The first - if deletion is successful:
[Response] => Array
(
[delete] => Array
(
[ip] => 127.0.0.100
[ownership] => true
[deleted] => true
)
)
The second if you are not allowed to delete an existing ip, that someone else added:
[Response] => Array
(
[delete] => Array
(
[ip] => 127.0.0.100
[ownership] => false
[deleted] => false
)
)
The third response shows up when trying to remove an address that doesnt exist in the databases:
[Response] => Array
(
[delete] => Array
(
[ip] => 127.0.0.100
[ownership] => false
[deleted] => false
[existip] => false
)
)
Trying to add or remove anything without the proper access will result in an error-response:
[error] => Array
(
[code] => 1
[message] => NoWrite
)
Where the error-code is currently associated to the constant DNSBL_PERMISSION_DENIED above.