Overview

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

Version information

Version : 1.0

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=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

report reponse

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,
  "attrs" : {
    "foo" : "bar"
  }
}

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 reponse

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 reponse

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 reponse

inline_response_200_1

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 reponse

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
}

Example HTTP response

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

POST /?command=reset

Description

Reset the stats 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 reponse

inline_response_200_2

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

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

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

msg
required

string

status
required

integer

inline_response_200_1

Name Description Schema

status
required

string

inline_response_200_2

Name Description Schema

msg
optional

string

status
required

string