Overview

An API to the Dovecot Anti-Abuse Shield to prevent brute-force and abuse of mail systems

Version information

Version : 1.2

Contact information

Contact : Dovecot Oy

License information

URI scheme

Host : doesnotexist.dovecot.fi
BasePath : /
Schemes : HTTP

Consumes

  • application/json

Produces

  • application/json

Paths

POST /?command=addBLEntry

Description

“Add a blacklist entry for an IP and/or login“

Parameters

Type Name Description Schema Default

Body

“addBLEntry”
required

Provide IP and/or login

AddBLEntryParams

Responses

HTTP Code Description Schema

200

“addBLEntry response"

inline_response_200

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "ip" : "127.0.0.1",
  "expire" : 3600,
  "reason" : "“Too many bad passwords”"
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

POST /?command=allow

Description

Query whether a login should be allowed

Parameters

Type Name Description Schema Default

Body

LoginTupleAllow
required

Login Tuple for allow command

LoginTupleAllow

Responses

HTTP Code Description Schema

200

“allow response"

inline_response_200_1

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "login" : "joe.bloggs",
  "remote" : "192.168.1.2",
  "pwhash" : "cc04",
  "success" : true,
  "attrs" : {
    "foo" : "bar"
  }
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

POST /?command=delBLEntry

Description

“Delete a blacklist entry for an IP and/or login“

Parameters

Type Name Description Schema Default

Body

“delBLEntry”
required

Provide IP and/or login

DelBLEntryParams

Responses

HTTP Code Description Schema

200

“delBLEntry response"

inline_response_200

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "ip" : "127.0.0.1"
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

GET /?command=getBL

Description

Get the list of all blacklisted IPs and/or Logins

Responses

HTTP Code Description Schema

200

getBL response

BLResponse

default

unexpected error

Error

Produces

  • application/json

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

POST /?command=getDBStats

Description

Get the db stats for an IP and/or login

Parameters

Type Name Description Schema Default

Body

GetDBStats
required

Provide IP and/or login

ResetStatsParams

Responses

HTTP Code Description Schema

200

getDBStats response

DBStatsResponse

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "ip" : "127.0.0.1"
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

GET /?command=ping

Description

Ping the server to ensure it is operational

Responses

HTTP Code Description Schema

200

ping response

inline_response_200

default

unexpected error

Error

Produces

  • application/json

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

POST /?command=report

Description

Creates a new report about a login (successful or unsuccessful)

Parameters

Type Name Description Schema Default

Body

LoginTupleReport
required

Login Tuple for report command

LoginTupleReport

Responses

HTTP Code Description Schema

200

report response

inline_response_200

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "login" : "joe.bloggs",
  "remote" : "192.168.1.2",
  "pwhash" : "cc04",
  "success" : true
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

POST /?command=reset

Description

Reset the stats and any blacklist entry for an IP and/or login

Parameters

Type Name Description Schema Default

Body

Reset
required

Provide IP and/or login

ResetStatsParams

Responses

HTTP Code Description Schema

200

reset response

inline_response_200

default

unexpected error

Error

Produces

  • application/json

Example HTTP request

Request body
{
  "ip" : "127.0.0.1"
}

Example HTTP response

Response default
{
  "status" : "failure",
  "reason" : "Unauthorized"
}

Definitions

AddBLEntryParams

Name Description Schema

expire_secs
optional

integer

ip
optional

string

login
optional

string

reason
optional

string

BLArray

Name Description Schema

ip
optional

BLEntry

iplogin
optional

BLEntry

login
optional

BLEntry

BLEntry

Type : < BLEntry_inner > array

BLEntry_inner

Name Description Schema

expiration
optional

string

key_name
optional

string

reason
optional

string

BLResponse

Name Description Schema

bl_entries
optional

< BLArray > array

DBStatsEntry

Name Description Schema

db_name
optional

DBStatsFields

DBStatsFields

Name Description Schema

field_name
optional

integer

DBStatsResponse

Name Description Schema

blacklisted
required

boolean

key_name
required

string

stats
required

DBStatsEntry

DelBLEntryParams

Name Description Schema

ip
optional

string

login
optional

string

Error

Name Description Schema

reason
required

string

status
required

string

LTAttrs

Name Description Schema

attr_name multi_value
optional

< string > array

attr_name_single_value
optional

string

LoginTupleAllow

Name Description Schema

attrs
optional

LTAttrs

login
required

string

pwhash
required

string

remote
required

string

LoginTupleReport

Name Description Schema

attrs
optional

LTAttrs

login
required

string

policy_reject
optional

boolean

pwhash
required

string

remote
required

string

success
required

boolean

ResetStatsParams

Name Description Schema

ip
optional

string

login
optional

string

inline_response_200

Name Description Schema

status
required

string

inline_response_200_1

Name Description Schema

msg
required

string

r_attrs
optional

inline_response_200_1_r_attrs

status
required

integer

inline_response_200_1_r_attrs

Name Description Schema

attr_name
optional

string