From 81bce9b76e6fbdfb493f06a9547a9a0ac46fcf14 Mon Sep 17 00:00:00 2001 From: Antoine MAZEAS Date: Fri, 28 Feb 2025 17:06:04 +0100 Subject: [PATCH 1/3] start creating a real documentation Signed-off-by: Antoine MAZEAS --- .ideconf/Build docs.run.xml | 20 +++++++++++ .ideconf/Serve web docs.run.xml | 28 +++++++++++++++ .ideconf/Tests.run.xml | 17 ++++++++++ Makefile | 3 ++ README.md | 6 ++-- docs/index.rst | 60 ++++++++++++++++++++++++++------- 6 files changed, 119 insertions(+), 15 deletions(-) create mode 100644 .ideconf/Build docs.run.xml create mode 100644 .ideconf/Serve web docs.run.xml create mode 100644 .ideconf/Tests.run.xml diff --git a/.ideconf/Build docs.run.xml b/.ideconf/Build docs.run.xml new file mode 100644 index 0000000..e456310 --- /dev/null +++ b/.ideconf/Build docs.run.xml @@ -0,0 +1,20 @@ + + + + + \ No newline at end of file diff --git a/.ideconf/Serve web docs.run.xml b/.ideconf/Serve web docs.run.xml new file mode 100644 index 0000000..29a4db4 --- /dev/null +++ b/.ideconf/Serve web docs.run.xml @@ -0,0 +1,28 @@ + + + + + \ No newline at end of file diff --git a/.ideconf/Tests.run.xml b/.ideconf/Tests.run.xml new file mode 100644 index 0000000..03776d9 --- /dev/null +++ b/.ideconf/Tests.run.xml @@ -0,0 +1,17 @@ + + + + + \ No newline at end of file diff --git a/Makefile b/Makefile index caabe67..3ff3e7c 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,11 @@ +.PHONY: build build: SOURCE_DATE_EPOCH=$(shell git log -1 --pretty=%ct) python3 -m build +.PHONY: clean clean: rm -rf *.egg-info/ build/ dist/ +.PHONY: clean.all clean.all: clean find . -type d -name .mypy_cache -o -name __pycache__ -exec rm -rf "{}" \+ diff --git a/README.md b/README.md index 3c60390..25ecf99 100644 --- a/README.md +++ b/README.md @@ -54,11 +54,13 @@ $ pip install -e . ### Client usage -To learn about how to use the OpenBAS Python client and read some examples and cases, refer to [the client documentation](https://openbas-client-for-python.readthedocs.io/en/latest/client_usage/getting_started.html). +To learn about how to use the OpenBAS Python client and read some examples and cases, +refer to [the client documentation](https://openbas-client-for-python.readthedocs.io/en/latest/client_usage/getting_started.html). ### API reference -To learn about the methods available for executing queries and retrieving their answers, refer to [the client API Reference](https://openbas-client-for-python.readthedocs.io/en/latest/pyobas/pyobas.html). +To learn about the methods available for executing queries and retrieving their answers, +refer to [the client API Reference](https://openbas-client-for-python.readthedocs.io/en/latest/pyobas/pyobas.html). ## Tests diff --git a/docs/index.rst b/docs/index.rst index 0b72a3d..1693319 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,56 @@ OpenBAS client for Python ========================= -The pyobas library is designed to help OpenBAS users and developers to interact -with the OpenBAS platform API. +The PyOBAS library is designed to help OpenBAS users and developers to interact +with the OpenBAS platform API using Python. It requires Python 3.11 or above. -The Python library requires Python >= 3. +Quickstart +========== -.. toctree:: - :maxdepth: 2 - :caption: Contents: +Installation +------------ +`PyOBAS is available via PyPI `_, so it may be installed with any good package manager. - client_usage/getting_started.rst - pyobas/pyobas +Install with ``pip``: +.. code:: shell -Indices and tables -================== + poetry add pyobas -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Or with ``poetry``: + +.. code:: shell + + poetry add pyobas + +Call into OpenBAS! +----- +As a demonstration, let's imagine we want to make a query for active users on a running OpenBAS server. + +.. code:: python + + from pyobas.client import OpenBAS; + + def main(): + # for example + url = "__OPENBAS_SERVER_URL__" + # find yours in your own profile on OpenBAS + token = "__API_TOKEN__" + + client = OpenBAS(url, token) + + users = client.user.list() + + for user in users: + print(user.user_email) + + if __name__ == "__main__": + main() + +Feature set +=========== +PyOBAS is not just an API client. + +* Interact with OpenBAS and query or modify its entities via a straightforward REST API +* Extend OpenBAS with custom Injectors, allowing for new capabilities +* Integrate with third-party security software suites to track the outcome of a simulated attack \ No newline at end of file From 4a03259fd916ab3f2214f7bc6a51aff124e6314f Mon Sep 17 00:00:00 2001 From: Antoine MAZEAS Date: Fri, 28 Feb 2025 17:06:31 +0100 Subject: [PATCH 2/3] forgot conf.py Signed-off-by: Antoine MAZEAS --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index ead483a..5f79d03 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ author = "OpenBAS Project" # The full version, including alpha/beta/rc tags -release = "1.10.1" +release = "1.12.2" master_doc = "index" From bca24e7e02d6c8ae89529c109328e9245b2ac666 Mon Sep 17 00:00:00 2001 From: Antoine MAZEAS Date: Fri, 28 Feb 2025 17:35:57 +0100 Subject: [PATCH 3/3] update Signed-off-by: Antoine MAZEAS --- docs/index.rst | 13 +++++++------ docs/requirements.txt | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 1693319..86d2471 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +========================= OpenBAS client for Python ========================= @@ -5,17 +6,17 @@ The PyOBAS library is designed to help OpenBAS users and developers to interact with the OpenBAS platform API using Python. It requires Python 3.11 or above. Quickstart -========== +---------- Installation ------------- +************ `PyOBAS is available via PyPI `_, so it may be installed with any good package manager. Install with ``pip``: .. code:: shell - poetry add pyobas + pip install pyobas Or with ``poetry``: @@ -23,8 +24,8 @@ Or with ``poetry``: poetry add pyobas -Call into OpenBAS! ------ +Usage example +************* As a demonstration, let's imagine we want to make a query for active users on a running OpenBAS server. .. code:: python @@ -48,7 +49,7 @@ As a demonstration, let's imagine we want to make a query for active users on a main() Feature set -=========== +----------- PyOBAS is not just an API client. * Interact with OpenBAS and query or modify its entities via a straightforward REST API diff --git a/docs/requirements.txt b/docs/requirements.txt index d47f7ff..79d93c1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ autoapi==2.0.1 -sphinx==7.4.7 +sphinx==8.2.1 sphinx-autodoc-typehints==3.1.0 sphinx_rtd_theme==3.0.2