Skip to content

Commit

Permalink
Merge pull request #44 from thehappydinoa/adh/update-docs
Browse files Browse the repository at this point in the history
Update Docs
  • Loading branch information
mattclement authored Sep 24, 2020
2 parents 79a1e5f + 7c42412 commit 1fe6caa
Show file tree
Hide file tree
Showing 8 changed files with 80 additions and 87 deletions.
2 changes: 2 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,5 @@ python:
version: 3.7
install:
- requirements: docs/requirements.txt
- method: pip
path: .
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ All contributions (no matter how small) are always welcome.

```bash
$ git clone git@github.com:censys/censys-python.git
$ pip install -e .[dev]
$ pip install -e ".[dev]"
```

## Testing
Expand Down
71 changes: 36 additions & 35 deletions censys/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,11 @@ class CensysAPISearch:
This class searches the Censys API, taking in options from the command line and
returning the results to a CSV or JSON file, or to stdout.
Kwargs:
format (str): Format of results: CSV, JSON, or stdout.
start_page (int): Page number to start from.
max_pages (int): The maximum number of pages of results to return.
api_secret (str): An API secret provided by Censys.
api_id (str): An API ID provided by Censys.
Args:
api_id (str, optional): The API ID provided by Censys.
api_secret (str, optional): The API secret provided by Censys.
start_page (int, optional): Page number to start from. Defaults to 1.
max_pages (int, optional): The maximum number of pages. Defaults to 10.
"""

csv_fields: Fields = list()
Expand All @@ -49,7 +48,6 @@ class CensysAPISearch:
def __init__(self, **kwargs):
self.api_user = kwargs.get("api_id")
self.api_pass = kwargs.get("api_secret")

self.start_page = kwargs.get("start_page", 1)
self.max_pages = kwargs.get("max_pages", 10)

Expand Down Expand Up @@ -88,8 +86,8 @@ def _write_json(file_path: str, search_results: Results) -> bool:
This method writes the search results to a new file in JSON format.
Args:
file_path (str): name of the file to write to on the disk.
search_results (Results): list of search results from API query.
file_path (str): Name of the file to write to on the disk.
search_results (Results): A list of results from the query.
Returns:
bool: True if wrote to file successfully.
Expand Down Expand Up @@ -193,9 +191,9 @@ def _process_search(
This method provides a common way to process searches from the API.
Args:
query: The string to send to the API as a query.
search_index: The data set to be queried - IPv4, Website, or Certificates.
fields: A list of fields to be returned for each result.
query (str): The string to send to the API as a query.
search_index (Index): The data set to be queried.
fields (Fields): A list of fields to be returned for each result.
Returns:
Results: A list of results from the query.
Expand Down Expand Up @@ -226,10 +224,11 @@ def search_ipv4(self, **kwargs) -> Results:
"""
A method to search the IPv4 data set via the API.
Kwargs:
query: The string search query.
fields: The fields that should be returned with a query.
overwrite: Overwrite the default list of fields with the given fields.
Args:
query (str): The string search query.
fields (list, optional): The fields that should be returned with a query.
overwrite (bool, optional): Whether to overwrite or append default fields
with user fields. Defaults to False.
Returns:
Results: A list of results from the query.
Expand Down Expand Up @@ -270,10 +269,10 @@ def search_certificates(self, **kwargs) -> Results:
A method to search the Certificates data set via the API.
Args:
kwargs:
query: The string search query.
fields: The fields that should be returned with a query.
overwrite: Overwrite the default list of fields with the given fields.
query (str): The string search query.
fields (list, optional): The fields that should be returned with a query.
overwrite (bool, optional): Whether to overwrite or append default fields
with user fields. Defaults to False.
Returns:
Results: A list of results from the query.
Expand Down Expand Up @@ -311,10 +310,10 @@ def search_websites(self, **kwargs) -> Results:
A method to search the Websites (Alexa Top 1M) data set via the API.
Args:
kwargs:
query: The string search query.
fields: The fields that should be returned with a query.
overwrite: Overwrite the default list of fields with the given fields.
query (str): The string search query.
fields (list, optional): The fields that should be returned with a query.
overwrite (bool, optional): Whether to overwrite or append default fields
with user fields. Defaults to False.
Returns:
Results: A list of results from the query.
Expand Down Expand Up @@ -347,9 +346,9 @@ class CensysHNRI:
"""
This class searches the Censys API, check the user's current IP for risks.
Kwargs:
api_secret (str): An API secret provided by Censys.
api_id (str): An API ID provided by Censys.
Args:
api_id (str, optional): The API ID provided by Censys.
api_secret (str, optional): The API secret provided by Censys.
"""

HIGH_RISK_DEFINITION: List[str] = ["telnet", "redis", "postgres", "vnc"]
Expand Down Expand Up @@ -476,10 +475,7 @@ def search(args):
args (Namespace): Argparse Namespace.
"""

censys_args = {"query": args.query}

if args.fields:
censys_args["fields"] = args.fields
censys_args = {}

if args.start_page:
censys_args["start_page"] = args.start_page
Expand All @@ -493,11 +489,16 @@ def search(args):
if args.api_secret:
censys_args["api_secret"] = args.api_secret

if args.overwrite:
censys_args["overwrite"] = args.overwrite

censys = CensysAPISearch(**censys_args)

search_args = {"query": args.query}

if args.fields:
search_args["fields"] = args.fields

if args.overwrite:
search_args["overwrite"] = args.overwrite

indexes = {
"ipv4": censys.search_ipv4,
"certs": censys.search_certificates,
Expand All @@ -507,7 +508,7 @@ def search(args):
index_type = args.index_type or args.query_type

index_func = indexes[index_type]
results = index_func(**censys_args)
results = index_func(**search_args)

try:
censys.write_file(results, file_format=args.format, file_path=args.output)
Expand Down
14 changes: 2 additions & 12 deletions docs/development.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,8 @@ Clone the repository:

Install dependencies via ``pip``:

.. tabs::

.. tab:: with macOS

.. prompt:: bash $
.. prompt:: bash $

pip install -e ".[dev]"

.. tab:: with Linux

.. prompt:: bash $

pip install -e .[dev]
pip install -e ".[dev]"

Run the test suite with ``pytest``. More information about testing is available at :ref:`testing:Testing`.
38 changes: 1 addition & 37 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,47 +9,11 @@ Welcome to Censys Python's documentation!
.. automodule:: censys
:members:

Quick start
-----------

Assuming you have Python already, install the package:

.. tabs::

.. tab:: from PyPi

.. prompt:: bash

pip install censys

.. tab:: from GitHub

.. prompt:: bash

pip install git+https://github.com/censys/censys-python@master

Configure your credentials:

.. tabs::

.. tab:: with CLI

.. prompt:: bash

censys config

.. tab:: with environment variables

.. prompt:: bash

export CENSYS_API_ID="XXX"
export CENSYS_API_SECRET="XXX"


.. toctree::
:maxdepth: 1
:caption: Table of Contents

quick-start
usage
cli
censys
Expand Down
35 changes: 35 additions & 0 deletions docs/quick-start.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
Quick Start
===========

Assuming you have Python already, install the package:

.. tabs::

.. tab:: from PyPi

.. prompt:: bash

pip install censys

.. tab:: from GitHub

.. prompt:: bash

pip install git+https://github.com/censys/censys-python@master

Configure your credentials:

.. tabs::

.. tab:: with CLI

.. prompt:: bash

censys config

.. tab:: with environment variables

.. prompt:: bash

export CENSYS_API_ID="XXX"
export CENSYS_API_SECRET="XXX"
3 changes: 2 additions & 1 deletion docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
sphinx
sphinx>=3.2.1
sphinxcontrib-napoleon
sphinxcontrib-autoprogram
sphinx-rtd-theme
sphinx-prompt
sphinx-tabs
Expand Down
2 changes: 1 addition & 1 deletion docs/testing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ To run the full test suite against your changes, simply run ``pytest``.

.. note::

Tests currently require credentials to be setup. More information about credentials is available at :ref:`index:Quick start`.
Tests currently require credentials to be setup. More information about credentials is available at :ref:`quick-start:Quick Start`.

.. prompt:: bash

Expand Down

0 comments on commit 1fe6caa

Please sign in to comment.