Logo

Docs

IP addresses

The IPv4 feeds is a set of end-points (API for simplicity) that provide access to Threat Inteligence information in connection to actors targeted by their IPv4.

GET latest IPv4 Feeds

You can call the API /api/v1/ips in order to receive an array of the latest IPv4 feeds collected at the OneFirewall Data lake.

HTTP Request

GET /api/v1/ips?page_size=512&ts=1684084988&full=yes HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
page_size 1 to 1000 (Integer) The maximum size of the array to retreive (Optional)
ts Timestamp from when to retreive data (Integer) (Optional)
full yes or no (String) full=yes provide more information (Optional)
Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 402 Payment Required: Not enogh OneFirewall Coins to perform the request
  • 401 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable

In case of an 200 response the body will be presented as the below example:

{
    "header": {
        "type": "IPv4",
        "version": 2,
        "ts": "1684014988",
        "page_size": 1,
        "delay": 0,
        "eval": "return (scoreTimeZero) / (1 + Math.exp( (3/(scoreTimeZero)) * ((current_time/3600) - (2.5 * scoreTimeZero))))",
        "exec_python": "score = (scoreTimeZero) / (1 + numpy.exp( (3/(scoreTimeZero)) * ((current_time/3600) - (2.5 * scoreTimeZero))))",
        "user": {
            "guid": "OFA-GUID-XXXX-XXXX-XXXX",
            "name": "Your name",
            "surname": "Your surname",
            "username": "Your email",
            "role": 0,
            "unsuccessful_login": 0,
            "member_of": {
                "gid": "OFA-GID-XXXXXXX",
                "name": "Organisation name",
                "trust": 0.9,
                "delay": "0"
            }
        }
    },
    "body": [
        {
            "gid": "OFA-RULE-GID-XXXXXX",
            "ip": "XXX.YYY.ZZZ.WWW",
            "ts": 1684015144,
            "entry_ts": 1683928684,
            "is_network": false,
            "ip_info": {
                "as_domain": "cloudflare.com",
                "as_name": "Cloudflare, Inc.",
                "asn": "AS13335",
                "continent": "NA",
                "continent_name": "North America",
                "country": "US",
                "country_name": "United States"
            },
            "score": 34,
            "info": {
                "members": 1,
                "events": 1,
                "sources": [
                    "sshlog"
                ],
                "stix_bundles": [],
                "attack_infos": [],
                "notes": [
                    "May 12 23:47:55 OFA-SRV2 sshd[12317]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost=XXX.YYY.ZZZ.WWW  user=root"
                ]
            },
            "elk_ts": "2023-05-13T21:59:04.000Z",
            "elk_entry_ts": "2023-05-12T21:58:04.000Z",
            "delay": 0,
            "dec": 8.3e-7
        }
    ]
}

The JSON in return is split into 2 objects:

  • header: Accountable to provide metadata of the request, the user who made the request and the organization where the users belong
  • body: Provide the data requested, in this case is an array of IPv4 feeds

Many of the information in the output are quite intuitive, therefore we explain only some of them:

Variable Possible Values Notes
version(header) 1 or 2 (Integer) The version of the platform (and not of the API)
page_size(header) 1 to 1000 (Integer) The size of the array (body) in return
eval(header) String NodeJS/JS function for score degradation in offline mode
exec_python(header) String Python function for score degradation in offline mode
user.member_of.trust(header) 0.0 to 1.0 (Float) Percentage of trust level of the member
user.member_of.delay(header) 0 to infinity (String) Delay of data imposed to the user (Governed by the License)
gid(body) String Unique ID of the feed as from OneFirewall data lake
ts(body) Timestamp (Integer) Latest update for the IPv4
entry_ts(body) Timestamp (Integer) First entry recorded for the IPv4
score(body) 0 to 1000 (Integer) Score at the moment of the TS
delay(body) 0 to infinity (Integer) Delay of data imposed to the Feed (Governed by the License)
dec(body) 0 to infinity (Long) Deprecated (please ignore)
info.members(body) 0 to 100k (Integer) Unique number of OneFirewall members reported the actor
info.events(body) 0 to 1m (Integer) Total reports for the specific actor
info.sources(body) Array of String List of sources from where is reported (not always populated)
info.notes(body) Array of String List of notes during the report (not always populated)

GET feeds for specific IPv4

You can call the API /api/v1/ips/<IPv4> in order to receive information for the IPv4 feeds in request if is presented at the OneFirewall Data lake. This API is useful when you want to verify if OneFirewall have an information for the actor in request.

HTTP Request

GET /api/v1/ips/<IPv4> HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
IPv4 IPv4 (String) A single IP
Output

The output of JSON is similar to when you retreive information about the latest IPs (please see table above)

POST an IPv4 Feeds

You can call the API /api/v1/ips/<IPv4> in order to receive information for the IPv4 feeds in request if is presented at the OneFirewall Data lake. This API is useful when you want to verify if OneFirewall have an information for the actor in request.

HTTP Request

POST /api/v1/ips HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Content-Type: application/json
Content-Length: 128

{
  "ip": "X.Y.Z.W",
  "confidence": 0.8,
  "notes": "OFA Test",
  "decision": -1,
  "ttl": null,
  "source": "webapp"
}
Input
Variable Possible Values Notes
ip IPv4 Format (String) An IPv4 format for single IP or Network
confidence 0.0 to 1.0 (Float) A percentace of confidence on the the actor being malicious
notes (String) Notes assocated to the actor (Optional)
decision -1, 0, 1 -1==no decision (default), 0==whitelist, 1==Block
ttl Timestamp (Integer) Until when the decision is valid (Optional)
source (String) The source from where the actor was identified
Output

The possible HTTP Code responses are:

  • 201 Created: The request was received and processed successfully (no body)
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 401 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable