Installation

When we speak about data and API access, we have to provide users with a Command Line Interface (CLI). That’s the best way to interact with APIs. Furthermore, we have created our own ONYPHE Processing Pipeline language called OPP.

It’s basically an expandable way of parsing JSON, like jq, but in a more easier way to play with. This OPP language is now also a standalone tool you can use on any JSON data.

Installation for Ubuntu/Debian/Kali systems

git clone https://github.com/onyphe/cli.git
cd cli
./install.sh

Installation for other systems

First, install your system cpanminus package. Then, install Perl dependencies:

git clone https://github.com/onyphe/cli.git
cd cli
./install.sh

sudo cpanm --no-lwp --from https://cpan.metacpan.org/ -n Mojolicious Config::INI::Tiny Tie::IxHash LWP::Protocol::https JSON::XS
sudo cpanm --no-lwp --from https://cpan.metacpan.org/ -n Text::ParseWords File::Slurp
sudo cpanm --no-lwp --from https://cpan.metacpan.org/ -n Regexp::IPv4 Text::CSV_XS Net::IPv4Addr Regexp::IPv6

perl Build.PL
./Build && ./Build test
sudo ./Build install

You’re done

To verify everything works, you can try the following queries:

onyphe -version

onyphe -help

onyphe -search 'protocol:http | uniq domain | addcount'

Installation using the docker image

For AMD64 / x86_64 architecture

Pull the latest image, default architecture is AMD64

docker pull onyphe/onyphecli:latest

For ARM64 architecture

Pull the image with the arm64 tag, then add the latest tag so that this image is used by default.

docker pull onyphe/onyphecli:arm64
docker tag onyphe/onyphecli:arm64 onyphe/onyphecli:latest

Testing the image

Running the image with no parameters returns the client version number.

docker run onyphe/onyphecli

Providing the API key

In order to query ONYPHE APIs it’s necessary to specify an API key. The simplest way of doing this with the docker image is to use the -key parameter, however this will result in your API key being visible in shell history and in process listings.

docker run onyphe/onyphecli -key YOUR_APIKEY -search 'category:datascan ip:8.8.8.8'

An alternative and probably better way is to create an .onyphe.ini file in your home directory and mount it in the container.

cd
echo 'api_endpoint = https://www.onyphe.io/api/v2' > ~/.onyphe.ini 
echo 'api_key = YOUR_APIKEY' >> ~/.onyphe.ini 

docker run -v $HOME:/root onyphe/onyphecli -search 'category:datascan ip:8.8.8.8'

A third option is to build the container image yourself with the API key added to the Dockerfile.

Creating an alias with the docker command and mount parameter allows for use of the dockerised client in an identical way to the native client.

alias onyphe='docker run -v $HOME:/root onyphe/onyphecli'

onyphe -search 'category:datascan domain:example.com protocol:rdp'

Add the alias command to your .profile or .bash_profile file to make it persistent.

Clean-up old containers

A container is created, run and shutdown each time the ONYPHE docker cli is called in this way. Clean-up old containers using the ‘docker container prune’ command.

Complete configuration options

Automatic paging

Maybe you want to setup automatic paging with Search API? There is an option for that. This option is activated by default with install.sh script.

WARNING: 1 query eats 1 credit. With automatic paging, you may consume up to 1,000 credits with a single -search query.

echo 'api_endpoint = https://www.onyphe.io/api/v2' > ~/.onyphe.ini
echo 'api_key = YOUR_APIKEY' >> ~/.onyphe.ini
echo 'api_maxpage = 1000' >> ~/.onyphe.ini

onyphe -search 'protocol:http | uniq domain | addcount'

For Unrated API option

We provide Unrated API access with a paid option to all our Enterprise licenses. Contact sales[at]onyphe{dot}io to learn more.

echo 'api_unrated_endpoint = https://www.onyphe.io/unrated/api/v2' > ~/.onyphe.ini
echo 'api_unrated_email = YOUR_LOGIN_EMAIL' >> ~/.onyphe.ini
echo 'api_key = YOUR_APIKEY' >> ~/.onyphe.ini
echo 'api_maxpage = 1000' >> ~/.onyphe.ini