Web detector

The Syspeace Web detector is a way of passing login attempts from other services, web sites and applications on the same server to Syspeace. With the help of a “reporter” integrated into or talking to the application, login attempts are reported to the web detector and picked up by Syspeace.

Web detector is available in Syspeace v4 in a beta implementation. Web detector is also available in Syspeace v3 bundled through the Detector Provider API/SDK.

To use the beta version of the web detector, please first upgrade to Syspeace Service 4.1.400 or newer.

Concepts

Detector: A detector is a source of login attempts used by Syspeace. Syspeace has multiple built-in detectors.

Web detector: The web detector is a Syspeace detector that accepts information about login attempts from other programs also running on the same server.

Reporter: A reporter is one of the other programs that can provide login attempt information. This is the username, the point in time, the login attempt outcome (success/failure), the IP address and the web site the login attempt was seen at. The program can be a standalone program or there can be a reporter component of another program or web site reacting to internal information about login attempts.

Reporting token: A reporting token is a kind of “password” that needs to be sent along with the reported information. If the reporting token does not match the expected token, the login attempt is not recorded by Syspeace. This can be used to avoid potential abuse, like another program, web site or script on the same server injecting false login attempts, which could lead to innocent IP addresses being blocked. Reporting tokens were optional in v3 but are required in v4.

Installation and configuration

To enable the web detector, create a plain text file named beta-web-detector.txt in:
Windows: the [Syspeace Service install folder]\appdata\ folder
Linux: /etc/opt/syspeace

This file lists all the web sites and their respective reporting token, as one or more lines of the format:

X=Y

X being the name of a web site, Y being the reporting token. If X is “*” (a single asterisk), this is the “wildcard” entry and Y is the reporting token for all web sites not otherwise named. There does not have to be a wildcard entry. If a web site has an entry, the wildcard entry is ignored.

As an example:

webmail=foobar
timereporting=diem
*=fallback

Here, these will work:

webmail with reporting token “foobar”
xyz with reporting token “fallback”
webmail2 with reporting token “fallback”

These will not work:

webmail with reporting token “fallback” (webmail has its own token)
xyz with reporting token “xyz” (wrong wildcard token)
webmail with reporting token “diem” (not the right token for webmail)

To make Syspeace Service read the file and use its configuration, restart the service.
Windows: restart the Syspeace4Service service
Linux: sudo systemctl restart syspeaced

You can now start using Web detector by reporting login attempts to it. See the Reporter specification.

In use in Syspeace Console

Login attempts from the web detector are entered as any other login attempts. The web site is recorded as a separate piece of information, and can be used as a condition in rules and when searching in Access Log.

FAQ

Q: What happens if I try to send login attempts that did not happen right now?
A: Login attempts that did not happen very recently are silently ignored.

Q: What happens if someone uses the wrong reporting token?
A: The response is the same regardless of whether the reporting token is correct or not.

Q: Do I need to use this for web sites?
A: No, not at all. A popular use of reporters is to send along information from systems Syspeace can’t see, which commonly are web sites or web applications, but can also be other types of negative signals.

Q: How is the information delivered from the reporter to the web detector?
A: The web detector starts a minimal web server listening only to the loopback network interface (ie not for external traffic), to which information can be posted. For details, see “Reporter specification“.

Q: What should a web site name consist of?
A: Anything except a “=” is allowed (since the “=” is the end of the web site name). Whitespace is trimmed from the start and end. If using characters beyond ASCII, save the file with the UTF-8 encoding.

Q: What should a reporting token consist of?
A: Reporting tokens should only consist of letters a-z, A-Z, numbers 0-9, underscore _ and hyphen -. Whitespace is trimmed from the start and end. The reporting tokens used in the example above are bad because they are short and theoretically guessable. Use a GUID generator or a secure password generator.

Reporter specification

A reporter should, when it wants to report a login attempt, send an HTTP POST request to http://localhost:60100/report with a JSON object in the request body fitting the following:

Key in object	Description
UserName	A string, the user trying to log in. Can be null if this information is not available.
IP	The IP address of the login attempt.
Success	A boolean: true if the login attempt was successful, false if it failed.
UTCTimestamp	The time when the login attempt was made. The time must be in the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ with T and Z being literal characters and with 24-hour hours. Note that this means the time must be in UTC/”GMT” and not in the system’s local time zone.
WebSite	The name of the web site.
ReportingToken	The reporting token configured for the web site. If the tokens do not match, the observation is not recorded.

The object keys are case sensitive.

Be prepared for the request to fail if the Web detector is not installed or started and handle this failure gracefully.

All reporters in the Syspeace v3 Detector SDK conform to this specification and may be used.