Metadata-Version: 2.4
Name: SilentPushCLI
Version: 1.3.0
Summary: Silent Push - Command Line Interface
Home-page: https://www.silentpush.com
Author: Jorgeley
Author-email: jorgeley@silentpush.com
License: https://www.silentpush.com/terms-of-use/
Keywords: cyber security,passive DNS
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: System Shells
Classifier: Topic :: Terminals
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: wcwidth==0.2.13
Requires-Dist: pyperclip==1.8.2
Requires-Dist: validators>=0.20.0
Requires-Dist: tldextract>=3.1.2
Requires-Dist: gnureadline>=8.1.2; sys_platform != "win32" and sys_platform != "win_amd64"
Requires-Dist: pandas==2.0.0; sys_platform == "win32" or sys_platform == "win_amd64"
Requires-Dist: iniconfig>=1.1.1
Requires-Dist: cmd2==2.7.0
Requires-Dist: pandas>=2.0.3; sys_platform != "win32" and sys_platform != "win_amd64"
Requires-Dist: pyparsing==3.1.1
Requires-Dist: attrs>=22.2.0
Requires-Dist: requests>=2.27.1
Requires-Dist: python-dotenv>=0.20.0
Requires-Dist: pyreadline3>=3.4.1; sys_platform == "win32" or sys_platform == "win_amd64"
Requires-Dist: numpy==1.26.4; sys_platform == "win32" or sys_platform == "win_amd64"
Requires-Dist: urllib3==1.26.6
Requires-Dist: jsonschema==4.17.3
Requires-Dist: py==1.11.0
Requires-Dist: pluggy>=1.0.0
Requires-Dist: xdg==5.1.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SP - CLI

The Silent Push CLI (Command Line Interface)

- [Requirements](#Requirements)

- [Installation](#Installation)

- [Usage](#Usage)

  - [Supported commands and sub-commands so far](#supported-commands-and-sub-commands-so-far)

  - [Options](#options)

- [Interactive mode](#interactive-mode)

  - [The load/unload command](#the-load-and-unload-command)

- [SPQL Commands](#spql-commands)

- [Scripting](#scripting)

  - [run_pyscript command](#runpyscript-command)

  - [run_script command](#runscript-command)

  - [Batch execution tips](#batch-execution-tips)

- [For Devs](#for-devs)

  - [Using the library](#using-the-library)

- [Support](#support)

## Requirements
- Python 3.9 or later with pip: https://www.python.org/downloads/
- Windows users only:
  - Microsoft Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/

## Installation
`python3 -m pip install SilentPushCLI`
### Linux and MacOS users
After installed, export your Silent Push API key to your terminal:
```shell
export SILENT_PUSH_API_KEY=YOUR-API-KEY
```
### Windows Users
After installed, export your Silent Push API key to your terminal:
```shell
setx /m SILENT_PUSH_API_KEY YOUR-API-KEY
```
Restart your CMD - Command Prompt

## Usage
Syntax:
```shell
sp COMMAND [SUB-COMMAND...] IOC [PARAMETER=VALUE...] [OPTION...]
```
Use the help verbose command to get a detailed list of the available commands:
```shell
sp help -v
```
Use the help flag on any command to get more details:
```shell
sp padns query a --help
```
Examples:
```shell
sp score ig.com
sp enrich ig.com -es
sp bulk_enrich ig.com x.com ibm.com -es
sp padns query a ig.com limit=2 sort=last_seen/- -t
```
### Supported commands and sub-commands so far
- score
- enrich
- bulk_enrich
- padns
  - query
    - any
    - anyipv4
    - anyipv6
    - a
    - aaaa
    - cname
    - mx
    - ns
    - ptr4
    - ptr6
    - soa
    - txt
  - answer
    - a
    - aaaa
    - cname
    - mx
    - mxhash
    - ns
    - nshash
    - ptr4
    - ptr6
    - soa
    - soahash
    - txt
    - txthash
- spql (multiline commands)
  - feedsearch
  - websearch
- threatcheck
- bulk_threatcheck
- load
- unload
### Options
- all commands
  - **-j, --json**: JSON output (default)
  - **-c, --csv**: CSV output
  - **-t, --tsv**: TSV output
  - **-h, --help**: show help
  - **-v, --verbose**: verbosity output
- enrich/bulk_enrich
  - **-e, --explain**: show details of data used to calculate the different scores in the response
  - **-s, --scan_data**: show details of data collected from host scanning

## Interactive mode
We also have an interactive console, If you type 'sp' alone, it will enter the 'sp console' and you can type commands without preceding 'sp', example:
```shell
SP# score ig.com
{
  "domain": "ig.com",
  "sp_risk_score": 18,
  "sp_risk_score_explain": {
    "sp_risk_score_decider": "ns_reputation_score"
  }
}

SP# padns query a ig.com limit=1
{
  "records": [
    {
      "answer": "195.234.39.132",
      "count": 2681,
      "first_seen": "2021-04-17 03:47:18",
      "last_seen": "2024-08-16 12:11:22",
      "query": "ig.com",
      "type": "A"
    }
  ]
}
```

### The load and unload command
This command gives you the ability of switching the console to a specific context and loading that group of commands.
As an example, 'padns' contains various sub-commands, so you can do like:
```shell
SP# load padns
PADNS loaded
SP (PADNS)# query ns ig.com limit=1
{
  "records": [
    {
      "answer": "dns1.p09.nsone.net",
      "count": 5963,
      "first_seen": "2020-12-26 00:41:26",
      "last_seen": "2024-08-16 09:25:09",
      "nshash": "981275157feda43a53ff6d166de985ff",
      "query": "ig.com",
      "ttl": 172800,
      "type": "NS"
    }
  ]
}

SP (PADNS)# answer ns dns1.p09.nsone.net limit=1
{
  "records": [
    {
      "answer": "dns1.p09.nsone.net",
      "count": 138,
      "first_seen": "2024-01-27 21:23:33",
      "last_seen": "2024-08-16 13:42:25",
      "nshash": "9b484fe18c1a52f56775302e5be302f8",
      "query": "tumblersforyou.com",
      "ttl": 3600,
      "type": "NS"
    }
  ]
}

SP (PADNS)# unload padns
PADNS unloaded
```
You still can use any other command normally.

## SPQL Commands
SPQL commands are multiline, since they can be quite complex. Use single quotes to span the query along the lines and use semicolon to finish it, example in interactive mode:
```shell
SP# websearch 'domain="ibm.com" 
  AND scan_date > "2025-01-01"' limit=2 -tv;
[
  {
    "HHV": "8c95d8a118b637509273f7a5d3",
    "adtech": {
      "ads_txt": false,
      "app_ads_txt": false,
      "sellers_json": false
    },
... (lots of results)
```
The same example but in a single line:
```shell
websearch 'domain="ibm.com" AND scan_date > "2025-01-01"' limit=2 -tv;
```

## Scripting
### run_pyscript command
There are 2 special commands for executing scripts using the 'sp' command, so you can
easily use it in your projects, here's a simple python script example:
```python
# my_script.py
result = app('score ibm.com -t')
print(result.data)
```
and this is how you can execute it:
```shell
sp run_pyscript my_script.py
```
### run_script command
Also, you can create a file with batch commands one per line and easily execute them, let's suppose we have this file:
```text
# my_script.txt
padns query mx ig.com limit=2
score ig.com -c 
```
and then you can execute this batch commands file with:
```shell
sp run_script my_script.txt
```
or you can simply redirect the input (like importing a database):
```shell
sp < my_script.txt
```
### Batch execution tips
As you might know already, one of the greatest feature of shell scripting is the ability of loading batch parameters from files.
Here's one idea for the bulk_enrich command:
```shell
cat to_enrich.txt | xargs sp bulk_enrich
```
Everything inside to_enrich.txt file will be treated as one parameter for the bulk_enrich command, don't mix domains with IPs though, 
since the command will depend on the type of enrichment being executed.

## For Devs
### Using the library
I you need to use the library on your own, here some examples:
```python
from sp.main import main as sp

sp(['enrich ig.com'])
sp(['padns query ns ig.com limit=2'])
```
another way of doing the same
```python
from sp.main import App
from sp.common.utils import AppFileManager

app = App(application_manager=AppFileManager('my app'))
app.onecmd_plus_hooks('enrich ig.com')
print(app.last_result)
app.onecmd_plus_hooks('padns query ns ig.com limit=2')
print(app.last_result)
```

## Support
Don't hesitate to contact me at [jorgeley@silentpush.com](jorgeley@silentpush.com) if you need any help
