From 8e7a3d8a172f62e13833f4d033b52e0cd38d66f6 Mon Sep 17 00:00:00 2001 From: Adam Janovsky Date: Tue, 26 Apr 2022 11:41:58 +0200 Subject: populate docs structure --- docs/installation.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/installation.md (limited to 'docs/installation.md') diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..0e6c025a --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,3 @@ +# Installation + +TBA \ No newline at end of file -- cgit v1.3.1 From e6a433e86be235cb4bfc0b80bcef719df42812d7 Mon Sep 17 00:00:00 2001 From: Adam Janovsky Date: Tue, 26 Apr 2022 16:10:36 +0200 Subject: add simple installation instr. and quickstart --- CONTRIBUTING.md | 7 +------ README.md | 22 +--------------------- docs/installation.md | 31 ++++++++++++++++++++++++++++++- docs/quickstart.md | 3 ++- 4 files changed, 34 insertions(+), 29 deletions(-) (limited to 'docs/installation.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80585c2d..542a39da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,12 +10,7 @@ You contribution is warmly welcomed. You can help by: ## Dependencies -Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/docker/Dockerfile) presents all the required dependencies, elaborated below. - -- [Java](https://www.java.com/en) is needed to parse tables in FIPS pdf documents, must be available from `PATH`. -- Some imported libraries have non-trivial dependencies to resolve: - - [pdftotext](https://github.com/jalan/pdftotext) requires [Poppler](https://poppler.freedesktop.org/) to be installed. We've experienced issues with older versions of Poppler (`0.x`), make sure to install `20.x` version of these libraries. - - [graphviz](https://pypi.org/project/graphviz/) requires `graphviz` to be on the path +For complete list of system dependencies, see [docs/installation](seccerts.org/docs/installation). ### Requirements diff --git a/README.md b/README.md index 69a036d3..6464900a 100644 --- a/README.md +++ b/README.md @@ -15,27 +15,7 @@ This project is developed by the [Centre for Research On Cryptography and Securi ## Installation -The tool can be pulled as a docker image with - -```bash -docker pull seccerts/sec-certs -``` - -Alternatively, it can be installed from PyPi with - -```bash -pip install -U sec-certs -``` - -Note, however, that `Python>=3.8` is required and there are some [additional dependencies](https://github.com/crocs-muni/sec-certs/blob/main/CONTRIBUTING.md#dependencies). - -The stable release is also published on [GitHub](https://github.com/crocs-muni/sec-certs/releases) from where it can be setup for development with - -```bash -python3 -m venv venv -source venv/bin/activate -pip install -e . -``` +Use Docker with `docker pull seccerts/sec-certs` or just `pip install -U sec-certs`. For more elaborate description, see [docs](seccerts.org/docs/installation) ## Usage (CC) diff --git a/docs/installation.md b/docs/installation.md index 0e6c025a..236a9dc9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,3 +1,32 @@ # Installation -TBA \ No newline at end of file +The tool can be pulled as a docker image with + +```bash +docker pull seccerts/sec-certs +``` + +Alternatively, it can be installed from PyPi with + +```bash +pip install -U sec-certs +``` + +Note, however, that `Python>=3.8` is required and there are some additional dependencies (see below) that are not shipped with the binary distribution. + +The stable release is also published on [GitHub](https://github.com/crocs-muni/sec-certs/releases) from where it can be setup for development with + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -e . +``` + +Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/docker/Dockerfile) represents a reproducible way of setting up the environment. + +## Dependencies + +- [Java](https://www.java.com/en) is needed to parse tables in FIPS pdf documents, must be available from `PATH`. +- Some imported libraries have non-trivial dependencies to resolve: + - [pdftotext](https://github.com/jalan/pdftotext) requires [Poppler](https://poppler.freedesktop.org/) to be installed. We've experienced issues with older versions of Poppler (`0.x`), make sure to install `20.x` version of these libraries. + - [graphviz](https://pypi.org/project/graphviz/) requires `graphviz` to be on the path \ No newline at end of file diff --git a/docs/quickstart.md b/docs/quickstart.md index b40bab01..74285025 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,3 +1,4 @@ # Quickstart -TBA \ No newline at end of file +1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)). +2. Use either `cc_cli.py` or `fips_cli.py` for full-fledged processing of the certificate pipeline, or explore the [dataset notebook](notebooks/dataset.ipynb). -- cgit v1.3.1 From 84c87543cd63bf4e04be7645c08ee8d6a80509a1 Mon Sep 17 00:00:00 2001 From: Adam Janovsky Date: Sun, 1 May 2022 20:11:03 +0200 Subject: fix consq. of moving dockerfile --- .github/workflows/release.yml | 6 ++--- docker/Dockerfile | 57 ------------------------------------------- docs/installation.md | 2 +- 3 files changed, 4 insertions(+), 61 deletions(-) delete mode 100644 docker/Dockerfile (limited to 'docs/installation.md') diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9063beaa..3a061417 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,5 @@ name: Release (PyPi, DockerHub) -on: +on: release: types: [published] @@ -27,7 +27,7 @@ jobs: docker_release: name: Release on DockerHub runs-on: ubuntu-latest - if: github.repository == 'crocs-muni/sec-certs' + if: github.repository == 'crocs-muni/sec-certs' steps: - name: Set up QEMU uses: docker/setup-qemu-action@v1 @@ -47,6 +47,6 @@ jobs: id: docker_build uses: docker/build-push-action@v2 with: - file: docker/Dockerfile + file: Dockerfile push: true tags: ${{ steps.meta.outputs.tags }} diff --git a/docker/Dockerfile b/docker/Dockerfile deleted file mode 100644 index eaf2d326..00000000 --- a/docker/Dockerfile +++ /dev/null @@ -1,57 +0,0 @@ -FROM ubuntu:jammy-20220428 - -ENV USER="user" -ENV NB_UID=1000 -ENV HOME /home/${USER} - -#installing dependencies -RUN apt-get update -RUN apt-get install python3 -y -RUN apt-get install python3-pip -y -RUN apt-get install python3-venv -y -RUN apt-get install git -y -RUN apt-get install curl -y - -# Install dependencies fo PyPDF2 and pdftotext -RUN DEBIAN_FRONTEND="noninteractive" apt-get -y install tzdata -RUN apt-get install build-essential libpoppler-cpp-dev pkg-config python3-dev -y -RUN apt-get install libqpdf-dev -y -RUN apt-get install default-jdk -y -RUN apt-get install graphviz -y - -RUN adduser --disabled-password \ - --gecos "Default user" \ - --uid ${NB_UID} \ - ${USER} - -RUN chown -R ${NB_UID} ${HOME} -USER ${USER} -WORKDIR ${HOME} - -# Download only snapshot of repository -RUN \ - curl -L https://api.github.com/repos/crocs-muni/sec-certs/tarball/main > sec-certs.tar.gz && \ - mkdir sec-certs && \ - tar zxf sec-certs.tar.gz --strip-components=1 --directory sec-certs && \ - rm sec-certs.tar.gz - -WORKDIR ${HOME}/sec-certs - -# Create virtual environment -ENV VENV_PATH=${HOME}/venv -RUN python3 -m venv ${VENV_PATH} -ENV PATH="${VENV_PATH}/bin:$PATH" - -# Install dependencies, notebook is because of mybinder.org -RUN \ - pip3 install -U pip && \ - pip3 install wheel && \ - pip3 install -r requirements/requirements.txt && \ - pip3 install --no-cache notebook jupyterlab && \ - pip3 install -e . - -# #just to be sure that pdftotext is in $PATH -ENV PATH /usr/bin/pdftotext:${PATH} - -# # Run the application: -# CMD ["python3", "./cc_cli.py"] diff --git a/docs/installation.md b/docs/installation.md index 236a9dc9..8d71a170 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -22,7 +22,7 @@ source venv/bin/activate pip install -e . ``` -Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/docker/Dockerfile) represents a reproducible way of setting up the environment. +Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/Dockerfile) represents a reproducible way of setting up the environment. ## Dependencies -- cgit v1.3.1 From 99768447af7031d4ceb982ba58f49fcf8d4c4591 Mon Sep 17 00:00:00 2001 From: Adam Janovsky Date: Fri, 20 May 2022 15:25:28 +0200 Subject: update docs --- docs/api/model.md | 22 ++++++++++++++++++++++ docs/index.md | 9 +++++---- docs/installation.md | 25 ++++++++++++++++++++----- docs/quickstart.md | 29 ++++++++++++++++++++++------- 4 files changed, 69 insertions(+), 16 deletions(-) (limited to 'docs/installation.md') diff --git a/docs/api/model.md b/docs/api/model.md index 372815c7..406d24be 100644 --- a/docs/api/model.md +++ b/docs/api/model.md @@ -1,5 +1,14 @@ # Model package +```{eval-rst} +.. automodule:: sec_certs.model + :no-members: +``` + +```{tip} +The examples related to this package can be found at [model notebook](./../notebooks/examples/model.ipynb). +``` + ## CPEClassifier ```{eval-rst} @@ -18,3 +27,16 @@ ## DependencyFinder +```{eval-rst} +.. currentmodule:: sec_certs.model +.. autoclass:: DependencyFinder + :members: +``` + +## DependencyVulnerabilityFinder + +```{eval-rst} +.. currentmodule:: sec_certs.model +.. autoclass:: DependencyVulnerabilityFinder + :members: +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 8e0883dc..3f44633b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,10 @@ Welcome to the technical documentation of *sec-certs* tool for the data analysis There are three main parts of this documentation. *User's guide* describes high-level use of our tool. Driven by this knowledge, you can progress to *Notebook examples* that showcase most of the API that we use in the form of Jupyter notebooks. The documentation currently does not have all modules documented with `autodoc`, so for the API reference, you must directly inspect the [sec_certs](https://github.com/crocs-muni/sec-certs/tree/main/sec_certs) module. If you want, you can run the notebooks as they are stored in the [project repository](https://github.com/crocs-muni/sec-certs/tree/main/notebooks). If you are interested in contributing to our project or in other aspects of our development, you can consult the relevant *GitHub artifacts* +```{admonition} Launch notebooks in MyBinder +Each of the notebooks can be launched interactively in MyBinder by clicking on 🚀 icon (top-right corner). +``` + ```{toctree} :hidden: :caption: Navigation @@ -24,6 +28,7 @@ tutorial.md :caption: Notebook examples notebooks/examples/common_criteria.ipynb notebooks/examples/fips.ipynb +notebooks/examples/model.ipynb ``` ```{toctree} @@ -31,10 +36,6 @@ notebooks/examples/fips.ipynb api/model.md ``` -```{admonition} Launch notebooks in MyBinder -Each of the notebooks can be launched interactively in MyBinder by clicking on 🚀 icon (top-right corner). -``` - ```{toctree} :maxdepth: 2 :caption: GitHub artifacts diff --git a/docs/installation.md b/docs/installation.md index 8d71a170..71e685db 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,18 +1,28 @@ # Installation -The tool can be pulled as a docker image with +::::{tab-set} +:::{tab-item} PyPi (pip) + +The tool can be installed from PyPi with ```bash -docker pull seccerts/sec-certs +pip install -U sec-certs ``` -Alternatively, it can be installed from PyPi with +Note, that `Python>=3.8` is required. + +::: + +:::{tab-item} Docker + +The tool can be pulled as a docker image with ```bash -pip install -U sec-certs +docker pull seccerts/sec-certs ``` -Note, however, that `Python>=3.8` is required and there are some additional dependencies (see below) that are not shipped with the binary distribution. +::: +:::{tab-item} Build from sources The stable release is also published on [GitHub](https://github.com/crocs-muni/sec-certs/releases) from where it can be setup for development with @@ -24,6 +34,11 @@ pip install -e . Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/Dockerfile) represents a reproducible way of setting up the environment. +::: +:::: + +If you're not using Docker, you must install the dependencies as described below. + ## Dependencies - [Java](https://www.java.com/en) is needed to parse tables in FIPS pdf documents, must be available from `PATH`. diff --git a/docs/quickstart.md b/docs/quickstart.md index 48f7f1ce..14121212 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,18 +1,29 @@ # Quickstart +::::{tab-set} + +:::{tab-item} Common Criteria 1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)). 2. Use ```python dset = CCDataset.from_web_latest() ``` +to obtain to obtain freshly processed dataset from [seccerts.org](https://seccerts.org). -(Common Criteria) or +3. Play with the dataset. See [example notebook](./notebooks/examples/common_criteria.ipynb). +::: +:::{tab-item} FIPS 140 +1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)). +2. Use ```python dset = FIPSDataset.from_web_latest() ``` +to obtain to obtain freshly processed dataset from [seccerts.org](https://seccerts.org). -(FIPS 140) to obtain freshly processed datasets from [seccerts.org](https://seccerts.org). +3. Play with the dataset. See [example notebook](./notebooks/examples/fips.ipynb). +::: +:::: ```{hint} You can work with those with the help of the [common criteria notebook](notebooks/examples/common_criteria.ipynb) or [fips notebook](notebooks/examples/fips.ipynb) and even launch them in MyBinder without installing anything. Just use the 🚀 icon (top-right corner). @@ -20,14 +31,18 @@ You can work with those with the help of the [common criteria notebook](notebook If you insist on processing the whole certificates pipeline, make sure that you installed all [dependencies](installation.md#dependencies). Then, run +::::{tab-set} +:::{tab-item} Common Criteria ```bash -cc-certs all +$ cc-certs all ``` +::: -for Common Criteria processing, or - +:::{tab-item} FIPS 140 ```bash -fips-certs all +$ fips-certs new-run ``` +::: +:::: -for FIPS 140 processing. This script takes a long time to run (few hours) and will create `./cc_dset` or `./fips_dset` directory. To see all options, call the entrypoint with `--help`. \ No newline at end of file +This script takes a long time to run (few hours) and will create `./cc_dset` or `./fips_dset` directory. To see all options, call the entrypoint with `--help`. \ No newline at end of file -- cgit v1.3.1