Custom Module Development - starter module to read and publishing process?

ghenry · February 21, 2023, 3:34pm

Hi all,

I’m looking to create a custom module which can be downloaded via Module Admin etc. where is the best place to start?

I was looking at github com/FreePBX-ContributedModules

It is a module to query an external RESTful API before querying the dialplan

Thanks.

jfinstrom · February 21, 2023, 5:38pm

This is a base module that will give you the general structure. a lot is documented in the wiki but it is currently down.

github.com

FreePBX/donotdisturb/blob/release/15.0/Api/Rest/Donotdisturb.php

<?php
namespace FreePBX\modules\Donotdisturb\Api\Rest;
use FreePBX\modules\Api\Rest\Base;
class Donotdisturb extends Base {
	protected $module = 'donotdisturb';
	public function setupRoutes($app) {

		/**
		* @verb GET
		* @return - a list of users' donotdisturb settings
		* @uri /donotdisturb/users
		*/
		$app->get('/users', function ($request, $response, $args) {
			\FreePBX::Modules()->loadFunctionsInc('donotdisturb');
			return $response->withJson(donotdisturb_get());
		})->add($this->checkAllReadScopeMiddleware());

		/**
		* @verb GET
		* @returns - a users' donotdisturb settings

This file has been truncated. show original

may be one of the simplest rest examples

lgaetz · February 21, 2023, 6:05pm

If you have an GNU GPL2+ licensed module that you want to contribute to the project, we can accept that provided you sign a Code Submission Agreement.

ghenry · February 21, 2023, 6:08pm

Thanks. It was to call an external API. I’ll have a play though

ghenry · February 21, 2023, 6:12pm

That would be fine. Was thinking AGPL.

I’m putting up a new API at SentryPeer com that allows users to check a numbed before it gets dialled to alert if it’s a toll fraud reconnaissance attempt. Details are collected by running your own SentryPeer org nodes that publish data to the same API.

The elixir / phoenix app will be AGPL once ready. APIs are all done and up though.

lgaetz · February 21, 2023, 6:24pm

Is this for inbound calls? If so, it might be better to add a CID Superfecta module for SentryPeer to do the API call there. Depending on the complexity of the API call, it may be possible to use one of the generic Regular Expression superfecta modules.

ghenry · February 21, 2023, 7:06pm

Hi @lgaetz

Thanks for that. This is for outbound calls. The idea, which I’m proving at the moment, is during the in-between stage of a handset/endpoint having a valid registration but it’s attempting to make test calls to see what the fraudster can do. We’ve all been there. An endpoint gets compromised somehow and you only know if your channel limits are reached or it starts calling Easter Island etc. We can catch them before that though and trigger alarms/alerts.

This is the gist from the SentryPeer project introduction (when running the standalone SentryPeer node with API enabled, not using the central sentrypeer com API):

SentryPeer® is a fraud detection tool. It lets bad actors try to make phone calls and saves the IP address they came from and number they tried to call. Those details can then be used to raise notifications at the service providers network/pbx and the next time a user/customer tries to call a collected number, you can act anyway you see fit.

For example:

Let’s say you are running your own VoIP PBX on site. What SentryPeer will allow you to do in this context, is dip into the list of phone numbers (using the RESTful API) when your users are making outbound calls. If you get a hit, you’ll get a heads-up that potentially a device within your network is trying to call known probing phone numbers that have either been:

Numbers collected by SentryPeer nodes you are running yourself

Numbers seen by other SentryPeer nodes which have been replicated to your node via the peer to peer network

This would allow you to generate a notification from your monitoring systems before you rack up any expensive calls or something worse happens.

What would lead to this scenario?

Potential voicemail fraud. This can happen if you allow calling an inbound number (your DID/DDI) to get to your voicemail system, then prompt for a PIN. This PIN is weak and the voicemail system allows you to press ‘*’ to call back the Caller ID that left a voicemail. The attacker has left a voicemail, and they then guess your PIN and call it back. The number called is a known number that SentryPeer has seen. You can alert on it.

A device has been hijacked and/or a softphone or similar is using the credentials they stole off the phone’s GUI and is registered to your system and make calls to a number seen by SentryPeer.

An innocent user is calling a phishing number or known expensive number etc. that SentryPeer has seen before.

Make sense?

Thanks.

ghenry · February 21, 2023, 11:24pm

Do you recommend starting with this too?

wiki freepbx org/display/FOP/FreePBX+Module+Generator

jfinstrom · February 22, 2023, 4:27am

That will generate basically the same thing as the helloworld with all the naming in place

ghenry · February 22, 2023, 5:47pm

Do you recommend I set this up or just use my fresh FreePBX 16 VirtualBox install?

wiki freepbx org/pages/viewpage.action?pageId=40468541

Setting up a Development environment from the FreePBX Distro (v14 and V15)

ghenry · February 23, 2023, 9:42pm

Getting pretty far now. agi php working. dialplan loading. Loading up. Got a few questions about installing the agi file and a few other things. Still OK on this post or start another?

What about a style guide? Is a logo OK?

I can’t seem to get this to stick SentryPeer-FreePBX-Module/Sentrypeer.class.php at main · SentryPeer/SentryPeer-FreePBX-Module · GitHub

How do I actually install the module again? Module Admin?

ghenry · February 23, 2023, 9:43pm

For example, config here:

github.com

SentryPeer/SentryPeer-FreePBX-Module/blob/d9c5d55ad7441e4a64e988b4a95b710521e8ed98/views/form.php#L37


      
          </div>
          <div class="element-container">
              <div class="row">
                  <div class="form-group">
                      <div class="col-md-3">
                          <label class="control-label" for="client-id"><?php echo _("SentryPeer Client ID") ?></label>
                          <i class="fa fa-question-circle fpbx-help-icon" data-for="client-id"></i>
                      </div>
                      <div class="col-md-9">
                          <input type="text" class="form-control" id="client-id" name="client-id"
                                 value="<?php echo $settings["sentrypeer-client-id"]; ?>">
                      </div>
                      <div class="col-md-3">
                          <label class="control-label"
                                 for="client-secret"><?php echo _("SentryPeer Client Secret") ?></label>
                          <i class="fa fa-question-circle fpbx-help-icon" data-for="client-secret"></i>
                      </div>
                      <div class="col-md-9">
                          <input type="text" class="form-control" id="client-secret"
                                 name="client-secret"
                                 value="<?php echo $settings["sentrypeer-client-secret"]; ?>">

and

github.com

SentryPeer/SentryPeer-FreePBX-Module/blob/main/Sentrypeer.class.php#L139


      
                          unset($buttons['delete']);
                      }
                      break;
              }
              return $buttons;
          }
          
          
public function showPage()
          {
          
          
    $subhead = _('Use SentryPeer® to help prevent VoIP cyberattacks, fraudulent VoIP phone calls (toll fraud) and improve cybersecurity by detecting early stage reconnaissance attempts.');
              $settings = array(
                  'sentrypeer-client-id' => $this->getConfig('sentrypeer-client-id') ? $this->getConfig('sentrypeer-client-id') : 'not-found',
                  'sentrypeer-client-secret' => $this->getConfig('sentrypeer-client-secret') ? $this->getConfig('sentrypeer-client-secret') : 'not-found',
              );
              $content = load_view(__DIR__ . '/views/form.php', array('settings' => $settings));
              show_view(__DIR__ . '/views/main.php', array('subhead' => $subhead, 'content' => $content));
          }
          
          
public function ajaxRequest($req, &$setting)
          {

jfinstrom · February 23, 2023, 11:16pm

getting anything commercial even under gpl in to official repos is already going to be a challenge. If you want your logo on it they will probably ask for fees etc. Just a guess.

When I am developing I put my module in /var/www/html/admin/modules/mymodule then run fwconsole ma install mymodule

not sure of the question here

Also notice the agi installs when you run apply config

ghenry · February 24, 2023, 9:54am

Thanks! My config isn’t working I think as I need to re-install the module so that hook runs.

ghenry · February 24, 2023, 5:23pm

Excellent! All done now.

Just one last question about my dialplan:

github.com

SentryPeer/SentryPeer-FreePBX-Module/blob/main/Sentrypeer.class.php#L70


      
              return 900;
          }
          
          
/**
           * Hook into Dialplan (extensions_additional.conf)
           * @method doDialplanHook
           * @param class $ext The Extensions Class https://wiki.freepbx.org/pages/viewpage.action?pageId=98701336
           * @param string $engine Always Asterisk, Legacy
           * @param string $priority Priority
           */
          public function doDialplanHook(&$ext, $engine, $priority)
          {
              $ext->addInclude('from-internal-additional', 'sentrypeer-context'); // Add the context to from-internal
              $mcontext = 'sentrypeer-context';
              $ext->add($mcontext, '_X!', '', new \ext_noop('Checking ${EXTEN} with SentryPeer'));
              $ext->add($mcontext, '_X!', '', new \ext_agi('sentrypeer.php, ${EXTEN}'));
          }
          
          
public function doConfigPageInit($page)
          {
          }

If the number dialled doesn’t match my outbound routes, then it hits the SentryPeer API, if it does match an outbound route, I can’t pick off the number to check it.

What’s the best context to go in? I have:

$ext->addInclude('from-internal-additional', 'sentrypeer-context');

Thanks.

lgaetz · February 24, 2023, 5:43pm

I haven’t read this thread in detail, but check the outbound cnam module. It hooks outbound call dialplan
https://git.freepbx.org/projects/FPBXCN/repos/outcnam/browse/Outcnam.class.php#101

Module page links to sentrypeer.com, should that be sentrypeer.org?

ghenry · February 24, 2023, 6:10pm

Thanks! Will have a read later tonight.

No, dot com is correct.

The code behind sentrypeer.com will be open-source too, released under the AGPLv3, published Q1.

We’ll be hosting it and you can run the SentryPeer node from sentrypeer.org to submit data to sentrypeer.com that they can then consume via its APIs for free. Hence this is free as in beer and free software.

Those that don’t want to do that can pay to access the data we’ve collected ourselves and other things. But the core platform is open-source to help with the trust part of the service. You can run the core platform that powers sentrypeer.com yourself with a bit of work.

sentrypeer.com SaaS/open-source backend is powered by Elixir/Phoenix Webframework/Phoenix LiveView and PostgreSQL.

It’s all open-source, but those that can’t be bothered to run things themselves can pay. Just like:

https://plausible.io/ and GitHub - plausible/analytics: Simple, open-source, lightweight (< 1 KB) and privacy-friendly web analytics alternative to Google Analytics.

Above is the same idea and tech (Elixir).

This is about detecting early fraud attempts before it costs customers/service providers money.

ghenry · February 24, 2023, 8:54pm

Maybe macro-dialout-one-predial-hook is a good place to be?

ghenry · February 27, 2023, 12:06pm

All working. Dialplan in the right place.

ghenry · February 27, 2023, 9:02pm

I’m happy with that! First release made:

Thanks for all the help everyone. I ended up creating a nice little custom context for others to hook into if needed:

github.com

SentryPeer/SentryPeer-FreePBX-Module/blob/main/Sentrypeer.class.php#L89


      
          $exten = "s";
          $webroot = $this->FreePBX->Config->get('AMPWEBROOT');
          // the dial macro will only exist if there is at least one outroute defined with a trunk
          // just checking for the existence of routes and trunks is not sufficient
          $routes = $this->FreePBX->Core->getAllRoutes();
          foreach ($routes as $route) {
              if (!empty($this->FreePBX->Core->getRouteTrunksByID($route['route_id']))) {
                  $dial_macro_exists = true;
              }
          }
          if ($dial_macro_exists) {
              // splice - https://wiki.freepbx.org/pages/viewpage.action?pageId=98701336
              $ext->splice($context, $exten, '', new \ext_set('ORIGINAL_NUM_FOR_SENTRYPEER', '${ARG2}'), "", 1);
              $ext->splice($context, $exten, "gocall", new \ext_noop('Checking ${ORIGINAL_NUM_FOR_SENTRYPEER} with SentryPeer'), "", 1);
              $ext->splice($context, $exten, "gocall", new \ext_agi('sentrypeer.php, ${ORIGINAL_NUM_FOR_SENTRYPEER}'), "", 2);
              $ext->splice($context, $exten, "gocall", new \ext_noop('SentryPeer Finished'), "", 3);
          
          
    // Add our own custom context so others can hook into it via extensions_custom.conf
              $ext->addInclude('macro-dialout-trunk', 'sentrypeer-context', 'For the SentryPeer service - https://sentypeer.com'); // Add the context to from-internal
              $mcontext = 'sentrypeer-context';
              $ext->add($mcontext, $exten, '', new \ext_noop('Number found on in the SentryPeer database. Hanging up the call.'));

Now back on to the server side of things!