Dovecot Anti-Abuse Shield

Overview

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

Version information

Version : 2.0

Contact information

Contact : Dovecot Oy

License information

License : GPL2
License URL : http://github.com/PowerDNS/weakforced/master/LICENSE

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

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

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

Type

Name

Description

Schema

Default

Body

LoginTupleAllow
required

LoginTupleAllow

Responses

HTTP Code	Description	Schema
200	“allow response"	inline_response_200_1
default	unexpected error	Error

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

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

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

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

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

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

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

Type

Name

Description

Schema

Default

Body

LoginTupleReport
required

LoginTupleReport

Responses

HTTP Code	Description	Schema
200	report response	inline_response_200
default	unexpected error	Error

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

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

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

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

Name

Description

Schema

ip
optional

BLEntry

iplogin
optional

BLEntry

login
optional

BLEntry

Type : < BLEntry_inner > array

BLEntry_inner

Name	Description	Schema
expiration optional		string
key_name optional		string
reason optional		string

Name

Description

Schema

expiration
optional

string

key_name
optional

string

reason
optional

string

BLResponse

Name	Description	Schema
bl_entries optional		< BLArray > array

Name

Description

Schema

bl_entries
optional

< BLArray > array

DBStatsEntry

Name	Description	Schema
db_name optional		DBStatsFields

Name

Description

Schema

db_name
optional

DBStatsFields

Name	Description	Schema
field_name optional		integer

Name

Description

Schema

field_name
optional

integer

DBStatsResponse

Name	Description	Schema
blacklisted required		boolean
key_name required		string
stats required		DBStatsEntry

Name

Description

Schema

blacklisted
required

boolean

key_name
required

string

stats
required

DBStatsEntry

DelBLEntryParams

Name	Description	Schema
ip optional		string
login optional		string

Name

Description

Schema

ip
optional

string

login
optional

string

Error

Name	Description	Schema
reason required		string
status required		string

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

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

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

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

Name

Description

Schema

ip
optional

string

login
optional

string

inline_response_200

Name	Description	Schema
status required		string

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

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

Name

Description

Schema

attr_name
optional

string