(12-12-2018, 11:41 PM)sunjester Wrote: Introduction
Like all my other tutorials this will be done within Ubuntu. Malshare is a website that allows you to share malware analysis reports and malware information in general. There are plenty of places like this on the internet such as virustotal and Jotti's and many many more. Malshare gives you 1,000 calls in a 24 hour period. You can also visit their Github page to follow issues. To login to this website you will need to register an API key and put it in the box in the top right of the page.



Exploring the Malshare API
You can view their existing documentation and REST API on their website. As you can see from the image below the API offers JSON and raw outputs. Each call is made with your API key. You can register for a key right here. From the API documentation we can write a class pretty easily.



Object Orientation
The whole philosophy for creating software is to make lives easier. When you write classes you need to keep in mind that object oriented programming is for code reuse. You want to write your code in such a way that you aren't rewriting it over and over again. Too many times people write code that they copy and paste over and over again when in fact they can simply write a class or a method/function. So below is a section of the class I started writing while reading the documentation.

Code:

<?php
class Malshare
{
       private $api_key;
       private $output;

       //make a new malshare
       function __construct($key)
       {
               $this->api_key = $key;
       }

       //make a call to the API
       function makeCall()
       {
       }

       ///api.php?api_key=[API_KEY]&action=getlist
       function listHashes()
       {
       }

The code above (unfinished) was written before I even did any planning whatsoever. Just because the API is short doesn't mean we don't need some kind of proper planning. You don't really want to rewrite code (called refactoring) over and over again. For example, I wrote some email marketing software in 2001 and it is still functioning to this day with being refactored once, when Google deprecated their old search API and started using the Custom Search API. The point is, I am going to write a function for each endpoint in the API but the code can still be refactored. For example, you could refactor these two methods into one with little effect.

Code:

///api.php?api_key=[API_KEY]&action=getlist
function listHashesJson()
{
}

///api.php?api_key=[API_KEY]&action=getlistraw
function listHashesRaw()
{
}

Making the Call
You can make calls to external sources in PHP in a few different ways. My favorite way is with CURL. However, these endpoints work just fine with a more simple way, file_get_contents(). This method has been around since PHP4 and it doesn't look like it's going away any time soon. Like they say in software, let's keep it simple. SO the call method will accept our complete API url and spit out the return data, like shown below.

Code:

$mal = new Malshare("6d9b0d--------------------------------2b5d9742a3");
$jsonHashes = $mal->listHashesJson();
die(var_dump($jsonHashes));

Uploading FIles
Down the list a bit on the API documentation page there is an option to upload a file. However, we have only been downloading data from the Malshare website. We can't use our usual function file_get_contents() for this, so we are going to use CURL. You can check your CURL version with the --version flag/argument.

Code:

(xenial)sunjester@localhost:/var/www/html/malshare$ curl --version
curl 7.47.0 (x86_64-pc-linux-gnu) libcurl/7.47.0 GnuTLS/3.4.10 zlib/1.2.8 libidn/1.32 librtmp/2.3
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP UnixSockets

If you read the CURL manpage you can see that the -F option is for uploading the file using the FormData field like their API needs. The image below is a screenshot of the manpage for CURL. The data field they want is called upload, and using it in a single CURL command (POST data) is simple, you can see that below as well.

Code:

curl -F "upload=@Malshare.php" "https://malshare.com/api.php?api_key=6d9b0d0236-----------5d9742a3&action=upload"

The return value is a hash of the file, which you can use to check with the earlier API methods we implemented in the Malshare class. However, executing this command in PHP is a bit different. You could probably just exec() the command and pull the results but it's much better to break it out into PHP code.



Conclusion
This is a simple tutorial on how to integrate the Malshare.com API into a PHP class. You can view the complete class on my github page.

(01-30-2019, 04:37 AM)darkninja1980 Wrote:

(12-12-2018, 11:41 PM)sunjester Wrote: Introduction
Like all my other tutorials this will be done within Ubuntu. Malshare is a website that allows you to share malware analysis reports and malware information in general. There are plenty of places like this on the internet such as virustotal and Jotti's and many many more. Malshare gives you 1,000 calls in a 24 hour period. You can also visit their Github page to follow issues. To login to this website you will need to register an API key and put it in the box in the top right of the page.



Exploring the Malshare API
You can view their existing documentation and REST API on their website. As you can see from the image below the API offers JSON and raw outputs. Each call is made with your API key. You can register for a key right here. From the API documentation we can write a class pretty easily.



Object Orientation
The whole philosophy for creating software is to make lives easier. When you write classes you need to keep in mind that object oriented programming is for code reuse. You want to write your code in such a way that you aren't rewriting it over and over again. Too many times people write code that they copy and paste over and over again when in fact they can simply write a class or a method/function. So below is a section of the class I started writing while reading the documentation.

Code:

<?php
class Malshare
{
       private $api_key;
       private $output;

       //make a new malshare
       function __construct($key)
       {
               $this->api_key = $key;
       }

       //make a call to the API
       function makeCall()
       {
       }

       ///api.php?api_key=[API_KEY]&action=getlist
       function listHashes()
       {
       }

The code above (unfinished) was written before I even did any planning whatsoever. Just because the API is short doesn't mean we don't need some kind of proper planning. You don't really want to rewrite code (called refactoring) over and over again. For example, I wrote some email marketing software in 2001 and it is still functioning to this day with being refactored once, when Google deprecated their old search API and started using the Custom Search API. The point is, I am going to write a function for each endpoint in the API but the code can still be refactored. For example, you could refactor these two methods into one with little effect.

Code:

///api.php?api_key=[API_KEY]&action=getlist
function listHashesJson()
{
}

///api.php?api_key=[API_KEY]&action=getlistraw
function listHashesRaw()
{
}

Making the Call
You can make calls to external sources in PHP in a few different ways. My favorite way is with CURL. However, these endpoints work just fine with a more simple way, file_get_contents(). This method has been around since PHP4 and it doesn't look like it's going away any time soon. Like they say in software, let's keep it simple. SO the call method will accept our complete API url and spit out the return data, like shown below.

Code:

$mal = new Malshare("6d9b0d--------------------------------2b5d9742a3");
$jsonHashes = $mal->listHashesJson();
die(var_dump($jsonHashes));

Uploading FIles
Down the list a bit on the API documentation page there is an option to upload a file. However, we have only been downloading data from the Malshare website. We can't use our usual function file_get_contents() for this, so we are going to use CURL. You can check your CURL version with the --version flag/argument.

Code:

(xenial)sunjester@localhost:/var/www/html/malshare$ curl --version
curl 7.47.0 (x86_64-pc-linux-gnu) libcurl/7.47.0 GnuTLS/3.4.10 zlib/1.2.8 libidn/1.32 librtmp/2.3
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP UnixSockets

If you read the CURL manpage you can see that the -F option is for uploading the file using the FormData field like their API needs. The image below is a screenshot of the manpage for CURL. The data field they want is called upload, and using it in a single CURL command (POST data) is simple, you can see that below as well.

Code:

curl -F "upload=@Malshare.php" "https://malshare.com/api.php?api_key=6d9b0d0236-----------5d9742a3&action=upload"

The return value is a hash of the file, which you can use to check with the earlier API methods we implemented in the Malshare class. However, executing this command in PHP is a bit different. You could probably just exec() the command and pull the results but it's much better to break it out into PHP code.



Conclusion
This is a simple tutorial on how to integrate the Malshare.com API into a PHP class. You can view the complete class on my github page.

great tutorial and also your GitHub I also like looking at as well.