Dovecot Anti-Abuse Shield (Wforce) (1.4.0)

Download OpenAPI specification:Download

License: GPL3

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

addBLEntry

Add a blacklist entry for an IP and/or login. Note that netmask and ip parameters are mutually exclusive.

Request Body schema: application/json

Provide IP and/or login

expire_secs	integer
ip	string
login	string
netmask	string
reason	string

Responses

Request samples

Payload

Content type

application/json

{"expire_secs": 3600,
"ip": "127.0.0.1",
"netmask": "2001:503:ba3e::/64",
"reason": "Too many bad passwords"
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

allow

Query whether a login should be allowed

Request Body schema: application/json

Login Tuple for allow command

	object (LTAttrs)
device_id	string
login required	string
protocol	string Enum: "http" "imap" "pop" "smtp" "mobileapi"
pwhash required	string
remote required	string
tls	boolean

Responses

Request samples

Payload

Content type

application/json

{"attrs": {"foo": "bar"
},
"login": "joe.bloggs",
"protocol": "http",
"pwhash": "cc04",
"remote": "192.168.1.2",
"success": true,
"tls": true
}

Response samples

200
default

Content type

application/json

{"msg": "string",
"r_attrs": {"two_factor_required": true
},
"status": 0
}

customEndpoint

Extensible mechanism allows custom REST endpoints to be defined - this is an example

Request Body schema: application/json

Arguments to custom REST endpoint

required

object (LTAttrs)

Responses

Request samples

Payload

Content type

application/json

{"attrs": {"key”:”value": null
}
}

Response samples

200
default

Content type

application/json

{"r_attrs": {"two_factor_required": true
},
"success": true
}

delBLEntry

Delete a blacklist entry for an IP and/or login. Note that netmask and ip parameters are mutually exclusive.

Request Body schema: application/json

Provide IP and/or login

ip	string
login	string
netmask	string

Responses

Request samples

Payload

Content type

application/json

{"ip": "127.0.0.1",
"netmask": "2001:503:ba3e/64"
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

getBL

Get the list of all blacklisted IPs and/or Logins

Responses

Response samples

200
default

Content type

application/json

{"bl_entries": [{"ip": [{"expiration": "2002-Jan-01 10:00:01",
"login": "joe.bloggs",
"reason": "Too many invalid login attempts from greylisted countries"
}
],
"iplogin": [{"expiration": "2002-Jan-01 10:00:01",
"login": "joe.bloggs",
"reason": "Too many invalid login attempts from greylisted countries"
}
],
"login": [{"expiration": "2002-Jan-01 10:00:01",
"login": "joe.bloggs",
"reason": "Too many invalid login attempts from greylisted countries"
}
]
}
]
}

getDBStats

Get the db stats for an IP and/or login

Request Body schema: application/json

Provide IP and/or login

ip	string
login	string

Responses

Request samples

Payload

Content type

application/json

{"ip": "127.0.0.1"
}

Response samples

200
default

Content type

application/json

{"blacklisted": true,
"key_name": "string",
"stats": {"db_name": {"countLogins": 239,
"diffPassword": 10
}
}
}

ping

Ping the server to ensure it is operational

Responses

Response samples

200
default

Content type

application/json

{"status": "ok"
}

report

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

Request Body schema: application/json

Login Tuple for report command

	object (LTAttrs)
device_id	string
login required	string
policy_reject	boolean
protocol	string Enum: "http" "imap" "pop3" "smtp" "mobileapi"
pwhash required	string
remote required	string
success required	boolean
tls	boolean

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
default

Content type

application/json

{"status": "ok"
}

reset

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

Request Body schema: application/json

Provide IP and/or login

ip	string
login	string

Responses

Request samples

Payload

Content type

application/json

{"ip": "127.0.0.1"
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

stats

Get server stats

Responses

Response samples

200
default

Content type

application/json

{"allows": 120321,
"denieds": 20201,
"perfstats": { },
"sys-msec": 97211221,
"user-msec": 292910108
}