CIDRAM integration in PHP projects

[mikeruss1]

Thinking of using one of the Project Honeypot PHP classes to detect undesirables. Is there an easy way for me to generate my own blocks and then use the cidram reporting features?

[mikeruss1]

Just to clarify that it doesn't need to be just Honeypot. If you publish an API it could be used for anything.

[Maikuolan]

Sorry for the delayed reply here. Busy day working all day yesterday and today, got home not too long ago, and actually feeling a little off at the moment. Just replying briefly now to confirm that I've seen this issue. I'll reply in more detail when I'm feeling a little more clear-headed, maybe later tonight or tomorrow at some point.

[mikeruss1]

Nothing urgent, maybe an idea for the future. I  can do a basic integration myself plus DB tracking. Would be helpful to be able to do a full reporting integration,or just be able to request a block.

⁣Cheers Mike​

On 16 Jan 2020, 09:58, at 09:58, Caleb Mazalevskis [e-mail] wrote:

Sorry for the delayed reply here. Busy day working all day yesterday
and today, got home not too long ago, and actually feeling a little off
at the moment. Just replying briefly now to confirm that I've seen this
issue. I'll reply in more detail when I'm feeling a little more
clear-headed, maybe later tonight or tomorrow at some point.

--
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub:
https://github.com/CIDRAM/CIDRAM/issues/165#issuecomment-575074860

[Maikuolan]

Good question. :-)

CIDRAM does already have generalised reporting functionality integrated into it, so technically, this should be possible. However, CIDRAM's generalised reporting functionality is totally undocumented at this time (aside from basic code commenting, that is; I mean undocumented in the sense of any actual markdown files or properly organised, dedicated documentation), so I would suggest that trying to leverage that functionality in customised code, modules, classes etc mightn't be particular easy at this time, and would entail a bit of a learning curve on part of whoever's writing said code/modules/classes/etc (not an unreasonably large learning curve, mind you, but slightly larger than the learning curve for just writing custom signature files or custom modules, owing to the fact that the process for writing custom signature files and custom modules is documented in great detail, whereas the generalised reporting functionality isn't yet documented at all).

The TL;DR version though, until I get around to documenting it: To report something somewhere, a "report handler" must be defined. Currently, the only module that actually does this, is the AbuseIPDB module. A copy/paste from the AbuseIPDB module to demonstrate this:

/** Add AbuseIPDB report handler. */
if ($CIDRAM['Config']['abuseipdb']['report_back']) {
    $CIDRAM['Reporter']->addHandler(function ($Report) use (&$CIDRAM) {
        $CIDRAM['InitialiseCacheSection']('RecentlyReported');
        if (isset($CIDRAM['RecentlyReported'][$Report['IP']])) {
            return;
        }
        $Categories = [];
        foreach ($Report['Categories'] as $Category) {
            if ($Category > 2 && $Category < 24) {
                $Categories[] = $Category;
            }
        }
        if (!count($Categories)) {
            return;
        }
        $Categories = implode(',', $Categories);
        $Status = $CIDRAM['Request']('https://api.abuseipdb.com/api/v2/report', [
            'ip' => $Report['IP'],
            'categories' => $Categories,
            'comment' => $Report['Comments']
        ], $CIDRAM['Timeout'], ['Key: ' . $CIDRAM['Config']['abuseipdb']['api_key'], 'Accept: application/json']);
        $CIDRAM['RecentlyReported'][$Report['IP']] = ['Status' => $Status, 'Time' => ($CIDRAM['Now'] + 900)];
        $CIDRAM['RecentlyReported-Modified'] = true;
    });
}

Then, once a a "report handler" has been defined, it'll be invoked whenever a module decides to report something (it can be the same module which defined the handler, or any other module; the order in which modules are loaded, or whether any particular module reports anything, doesn't matter; even if a report is made before the handler is defined, CIDRAM will still be able to figure out what to do).

Most of the modules I've made available already have the ability to report things regarded as report-worthy.

As an example, the optional security extras module includes this towards the bottom of the file:

        /** Probing for vulnerable routers. */
        if ($Trigger(preg_match('~^/*HNAP1~i', $LCReqURI), 'Probing for vulnerable routers')) {
            $CIDRAM['Reporter']->report([15, 23], ['Caught probing for vulnerable routers.'], $CIDRAM['BlockInfo']['IPAddr']);
        } // 2019.08.12

Basically, this means that if a user has installed both the AbuseIPDB module and the optional security extras module, and the signature for "probing for vulnerable routers" in the latter is triggered, the latter can use the former's report handler to send a report about the incident to AbuseIPDB.

The same could be done for Project Honeypot, or for any other API anywhere, but the relevant code would still need to written up to do so in the first place (i.e., writing the report handler).

If a module tries to report something, but no report handlers have been defined, the reports will just be silently discarded when CIDRAM finishes processing everything, so we don't need to worry about errors and things like that occurring due to missing handlers.

Seeing as the AbuseIPDB module is currently the only module that defines any report handler, the "report categories" (information that tells us more about the reason why a report was made, in a programmatic manner; useful as a means to allow handlers to discard reports that aren't pertinent to the API that they're reporting to and so on) available to the "report orchestrator" (the part of the codebase responsible for invoking as necessary any report handlers whenever any reports are made), at this time, are closely related to the report categories provided by AbuseIPDB's own API itself, but I'd had it in mind that they can just be easily expanded to suit the needs of whichever APIs might be contacted by any report handlers that might be defined in the future.

(Yeah.. I know this reply is getting quite long.. still a TL;DR version compared to the length of the documentation that'll likely actually be eventually needed though).

[Maikuolan]

But yeah.. When I eventually get around to finishing off the Project Honeypot module for CIDRAM, I'm aiming to have a report handler included with it.

[mikeruss1]

thanks (broadly) understood.
when you get around to it an example would be most helpful.

[mikeruss1]

just to add a reverse possibility, to be able to use the IP tracking status of CIDRAM in an external project.

[mikeruss1]

and another thought, blocked and reported elsewhere, but add IP to your tracking database.

again not crucial, just nice to have