OX Abuse Shield (Wforce) (2.6.1)

Download OpenAPI specification:Download

License: GPL3

An API to the 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": "Is there ever a good reason"
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

addSibling

This is a request to add a new Sibling for replication purposes.

Request Body schema: application/json

Details about the Sibling to add

encryption_key	string
sibling_host required	string
sibling_port required	integer
sibling_protocol	string Enum: "tcp" "udp"

Responses

Request samples

Payload

Content type

application/json

{"encryption_key": "string",
"sibling_host": "string",
"sibling_port": 0,
"sibling_protocol": "tcp"
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

addWLEntry

Add a whitelist 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": "Is there ever a good reason"
}

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"
}
}

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"
}

delWLEntry

Delete a whitelist 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"
}

dumpEntries

This is a request to dump StatsDB entries (consisting of the values of each of the time windows for each field) to a specified IP address and port over TCP.

Request Body schema: application/json

The ip and port to dump to

dump_host required	string
dump_port required	integer

Responses

Request samples

Payload

Content type

application/json

{"dump_host": "string",
"dump_port": 0
}

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

{"bl_expire": "string",
"bl_reason": "string",
"blacklisted": true,
"key_name": "string",
"stats": {"db_name": {"countLogins": 239,
"diffPassword": 10
}
},
"whitelisted": true,
"wl_expire": "string",
"wl_reason": "string"
}

getWL

Get the list of all whitelisted 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"
}
]
}
]
}

ping

Ping the server to ensure it is operational

Responses

Response samples

200
default

Content type

application/json

{"status": "ok"
}

removeSibling

This is a request to add remove a Sibling for replication purposes.

Request Body schema: application/json

Details about the Sibling to remove

sibling_host required	string
sibling_port required	integer

Responses

Request samples

Payload

Content type

application/json

{"sibling_host": "string",
"sibling_port": 0
}

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"
}

setSiblings

This is a request to set the Siblings for replication purposes.

Request Body schema: application/json

Details about the Sibling to add

Array of objects[ items ]

Responses

Request samples

Payload

Content type

application/json

{"siblings": [{"encryption_key": "string",
"sibling_host": "string",
"sibling_port": 0,
"sibling_protocol": "tcp"
}
]
}

Response samples

200
default

Content type

application/json

{"status": "ok"
}

stats

Get server stats (deprecated - will be removed in future version)

Responses

Response samples

200
default

Content type

application/json

{"allows": 120321,
"commandstats": {"addBLEntry": 0,
"addWLEntry": 1,
"allow": 8,
"allow_allowed": 4,
"allow_blacklisted": 0