From a07429e54098248c1c296d412f2fdac2f1fd5408 Mon Sep 17 00:00:00 2001 From: Adam Janovsky Date: Sat, 10 Dec 2022 09:16:18 +0100 Subject: rename notebook common_criteria -> cc --- docs/api/dataset.md | 2 +- docs/api/sample.md | 2 +- docs/index.md | 2 +- docs/quickstart.md | 4 +- notebooks/examples/cc.ipynb | 257 +++++++++++++++++++++++++++++++ notebooks/examples/common_criteria.ipynb | 257 ------------------------------- 6 files changed, 262 insertions(+), 262 deletions(-) create mode 100644 notebooks/examples/cc.ipynb delete mode 100644 notebooks/examples/common_criteria.ipynb diff --git a/docs/api/dataset.md b/docs/api/dataset.md index 27a77e79..71ed9f76 100644 --- a/docs/api/dataset.md +++ b/docs/api/dataset.md @@ -8,7 +8,7 @@ This documentation doesn't provide full API reference for all members of `dataset` package. Instead, it concentrates on the Dataset that are immediately exposed to the users. Namely, we focus on `CCDataset`, `FIPSDataset` and their abstract base class `Dataset`. ```{tip} -The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/common_criteria.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb). +The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/cc.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb). ``` ## CCDataset diff --git a/docs/api/sample.md b/docs/api/sample.md index c07f319c..fe46a4a1 100644 --- a/docs/api/sample.md +++ b/docs/api/sample.md @@ -6,7 +6,7 @@ ``` ```{tip} -The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/common_criteria.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb). +The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/cc.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb). ``` ## CCCertificate diff --git a/docs/index.md b/docs/index.md index 94694910..0b0ba966 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,7 +43,7 @@ configuration.md :caption: Notebook examples :hidden: True :maxdepth: 1 -notebooks/examples/common_criteria.ipynb +notebooks/examples/cc.ipynb notebooks/examples/fips.ipynb notebooks/examples/model.ipynb notebooks/examples/fips_iut.ipynb diff --git a/docs/quickstart.md b/docs/quickstart.md index de0c64f0..57033259 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -12,7 +12,7 @@ dset = CCDataset.from_web_latest() ``` to obtain to obtain freshly processed dataset from [seccerts.org](https://seccerts.org). -3. Play with the dataset. See [example notebook](./notebooks/examples/common_criteria.ipynb). +3. Play with the dataset. See [example notebook](./notebooks/examples/cc.ipynb). ::: :::{tab-item} FIPS 140 @@ -30,7 +30,7 @@ to obtain to obtain freshly processed dataset from [seccerts.org](https://seccer :::: ```{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). +You can work with those with the help of the [common criteria notebook](notebooks/examples/cc.ipynb) or [fips notebook](notebooks/examples/fips.ipynb) and even launch them in MyBinder without installing anything. Just use the 🚀 icon (top-right corner). ``` If you insist on processing the whole certificates pipeline, make sure that you installed all [dependencies](installation.md#dependencies). Then, run diff --git a/notebooks/examples/cc.ipynb b/notebooks/examples/cc.ipynb new file mode 100644 index 00000000..fe53be27 --- /dev/null +++ b/notebooks/examples/cc.ipynb @@ -0,0 +1,257 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Common Criteria example\n", + "\n", + "This notebook illustrates basic functionality with the `CCDataset` class that holds Common Criteria dataset and of its sample `CCCertificate`.\n", + "\n", + "Note that there exists a front end to this functionality at [seccerts.org/cc](https://seccerts.org/cc/). Before reinventing the wheel, it's good idea to check our web. Maybe you don't even need to run the code, but just use our web instead. " + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "from sec_certs.dataset import CCDataset\n", + "from sec_certs.sample import CCCertificate\n", + "import pandas as pd" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Get fresh dataset snapshot from mirror\n", + "\n", + "There's no need to do full processing of the dataset by yourself, unless you modified `sec-certs` code. You can simply fetch the processed version from the web. \n", + "\n", + "Note, however, that you won't be able to access the `pdf` and `txt` files of the certificates. You can only get the data that we extracted from it. \n", + "\n", + "Running the whole pipeline can get you the `pdf` and `txt` data. You can see how to do that in the last cell of this notebook." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dset = CCDataset.from_web_latest()\n", + "print(len(dset)) # Print number of certificates in the dataset" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do some basic dataset serialization\n", + "\n", + "The dataset can be saved/loaded into/from `json`. Also, the dataset can be converted into a [pandas](https://pandas.pydata.org/) DataFrame. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Dump dataset into json and load it back\n", + "dset.to_json(\"./cc_dset.json\")\n", + "new_dset: CCDataset = CCDataset.from_json(\"./cc_dset.json\")\n", + "assert dset == new_dset" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Turn dataset into Pandas DataFrame\n", + "df = dset.to_pandas()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Simple dataset manipulation\n", + "\n", + "The certificates of the dataset are stored in a dictionary that maps certificate's primary key (we call it `dgst`) to the `CCCertificate` object. The primary key of the certificate is simply a hash of the attributes that make the certificate unique.\n", + "\n", + "You can iterate over the dataset which is handy when selecting some subset of certificates." + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "metadata": {}, + "outputs": [], + "source": [ + "# Iterate over certificates in dataset\n", + "for cert in dset:\n", + " pass\n", + "\n", + "# Get certificates produced by Infineon manufacturer\n", + "infineon_certs = [x for x in dset if \"Infineon\" in x.manufacturer]\n", + "df_infineon = df.loc[df.manufacturer.str.contains(\"Infineon\", case=False)]\n", + "\n", + "# Get certificates with some CVE\n", + "vulnerable_certs = [x for x in dset if x.heuristics.related_cves]\n", + "df_vulnerable = df.loc[~df.related_cves.isna()]\n", + "\n", + "# Show CVE ids of some vulnerable certificate\n", + "print(f\"{vulnerable_certs[0].heuristics.related_cves=}\")\n", + "\n", + "# Get certificates from 2015 and newer\n", + "df_2015_and_newer = df.loc[df.year_from > 2014]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Plot distribution of years of certification\n", + "df.year_from.value_counts().sort_index().plot.line()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Dissect single certificate\n", + "\n", + "The `CCCertificate` is basically a data structure that holds all the data we keep about a certificate. Other classes (`CCDataset` or `model` package members) are used to transform and process the certificates. You can see all its attributes at [API docs](https://seccerts.org/docs/api/sample.html)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Select a certificate and print some attributes\n", + "cert: CCCertificate = dset[\"bad93fb821395db2\"]\n", + "print(f\"{cert.name=}\")\n", + "print(f\"{cert.heuristics.cpe_matches=}\")\n", + "print(f\"{cert.heuristics.report_references.directly_referencing=}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "# Select all certificates from a dataset for which we detect at least one vulnerability.\n", + "vulnerable_certs = [x for x in dset if x.heuristics.related_cves]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Serialize single certificate\n", + "\n", + "Again, a certificate can be (de)serialized into/from json. It's also possible to construct pandas `Series` from a certificate as shown below" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "cert.to_json(\"./cert.json\")\n", + "new_cert = cert.from_json(\"./cert.json\")\n", + "assert cert == new_cert\n", + "\n", + "# Serialize as Pandas series\n", + "ser = pd.Series(cert.pandas_tuple, index=cert.pandas_columns)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Assign dataset with CPE records and compute vulnerabilities\n", + "\n", + "*Note*: The data is already computed on dataset obtained with `from_web_latest()`, this is just for illustration. \n", + "*Note*: This may likely not run in Binder, as the corresponding `CVEDataset` and `CPEDataset` instances take a lot of memory." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Automatically match CPEs and CVEs\n", + "dset.compute_cpe_heuristics()\n", + "dset.compute_related_cves()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Create new dataset and fully process it\n", + "\n", + "The following piece of code roughly corresponds to `$ cc-certs all` CLI command -- it fully processes the CC pipeline. This will create a folder in current working directory where the outputs will be stored. \n", + "\n", + "*Warning*: It's not good idea to run this from notebook. It may take several hours to finnish. We recommend using `from_web_latest()` or turning this into a Python script." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dset = CCDataset()\n", + "dset.get_certs_from_web()\n", + "dset.process_auxillary_datasets()\n", + "dset.download_all_artifacts()\n", + "dset.convert_all_pdfs()\n", + "dset.analyze_certificates()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3.8.13 ('venv': venv)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.13 (default, Jul 27 2022, 12:09:23) \n[Clang 13.1.6 (clang-1316.0.21.2.3)]" + }, + "orig_nbformat": 4, + "vscode": { + "interpreter": { + "hash": "a5b8c5b127d2cfe5bc3a1c933e197485eb9eba25154c3661362401503b4ef9d4" + } + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/notebooks/examples/common_criteria.ipynb b/notebooks/examples/common_criteria.ipynb deleted file mode 100644 index fe53be27..00000000 --- a/notebooks/examples/common_criteria.ipynb +++ /dev/null @@ -1,257 +0,0 @@ -{ - "cells": [ - { - "attachments": {}, - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Common Criteria example\n", - "\n", - "This notebook illustrates basic functionality with the `CCDataset` class that holds Common Criteria dataset and of its sample `CCCertificate`.\n", - "\n", - "Note that there exists a front end to this functionality at [seccerts.org/cc](https://seccerts.org/cc/). Before reinventing the wheel, it's good idea to check our web. Maybe you don't even need to run the code, but just use our web instead. " - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "from sec_certs.dataset import CCDataset\n", - "from sec_certs.sample import CCCertificate\n", - "import pandas as pd" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Get fresh dataset snapshot from mirror\n", - "\n", - "There's no need to do full processing of the dataset by yourself, unless you modified `sec-certs` code. You can simply fetch the processed version from the web. \n", - "\n", - "Note, however, that you won't be able to access the `pdf` and `txt` files of the certificates. You can only get the data that we extracted from it. \n", - "\n", - "Running the whole pipeline can get you the `pdf` and `txt` data. You can see how to do that in the last cell of this notebook." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dset = CCDataset.from_web_latest()\n", - "print(len(dset)) # Print number of certificates in the dataset" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Do some basic dataset serialization\n", - "\n", - "The dataset can be saved/loaded into/from `json`. Also, the dataset can be converted into a [pandas](https://pandas.pydata.org/) DataFrame. " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Dump dataset into json and load it back\n", - "dset.to_json(\"./cc_dset.json\")\n", - "new_dset: CCDataset = CCDataset.from_json(\"./cc_dset.json\")\n", - "assert dset == new_dset" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Turn dataset into Pandas DataFrame\n", - "df = dset.to_pandas()" - ] - }, - { - "attachments": {}, - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Simple dataset manipulation\n", - "\n", - "The certificates of the dataset are stored in a dictionary that maps certificate's primary key (we call it `dgst`) to the `CCCertificate` object. The primary key of the certificate is simply a hash of the attributes that make the certificate unique.\n", - "\n", - "You can iterate over the dataset which is handy when selecting some subset of certificates." - ] - }, - { - "cell_type": "code", - "execution_count": 40, - "metadata": {}, - "outputs": [], - "source": [ - "# Iterate over certificates in dataset\n", - "for cert in dset:\n", - " pass\n", - "\n", - "# Get certificates produced by Infineon manufacturer\n", - "infineon_certs = [x for x in dset if \"Infineon\" in x.manufacturer]\n", - "df_infineon = df.loc[df.manufacturer.str.contains(\"Infineon\", case=False)]\n", - "\n", - "# Get certificates with some CVE\n", - "vulnerable_certs = [x for x in dset if x.heuristics.related_cves]\n", - "df_vulnerable = df.loc[~df.related_cves.isna()]\n", - "\n", - "# Show CVE ids of some vulnerable certificate\n", - "print(f\"{vulnerable_certs[0].heuristics.related_cves=}\")\n", - "\n", - "# Get certificates from 2015 and newer\n", - "df_2015_and_newer = df.loc[df.year_from > 2014]" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Plot distribution of years of certification\n", - "df.year_from.value_counts().sort_index().plot.line()" - ] - }, - { - "attachments": {}, - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Dissect single certificate\n", - "\n", - "The `CCCertificate` is basically a data structure that holds all the data we keep about a certificate. Other classes (`CCDataset` or `model` package members) are used to transform and process the certificates. You can see all its attributes at [API docs](https://seccerts.org/docs/api/sample.html)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Select a certificate and print some attributes\n", - "cert: CCCertificate = dset[\"bad93fb821395db2\"]\n", - "print(f\"{cert.name=}\")\n", - "print(f\"{cert.heuristics.cpe_matches=}\")\n", - "print(f\"{cert.heuristics.report_references.directly_referencing=}\")" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [], - "source": [ - "# Select all certificates from a dataset for which we detect at least one vulnerability.\n", - "vulnerable_certs = [x for x in dset if x.heuristics.related_cves]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Serialize single certificate\n", - "\n", - "Again, a certificate can be (de)serialized into/from json. It's also possible to construct pandas `Series` from a certificate as shown below" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [], - "source": [ - "cert.to_json(\"./cert.json\")\n", - "new_cert = cert.from_json(\"./cert.json\")\n", - "assert cert == new_cert\n", - "\n", - "# Serialize as Pandas series\n", - "ser = pd.Series(cert.pandas_tuple, index=cert.pandas_columns)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Assign dataset with CPE records and compute vulnerabilities\n", - "\n", - "*Note*: The data is already computed on dataset obtained with `from_web_latest()`, this is just for illustration. \n", - "*Note*: This may likely not run in Binder, as the corresponding `CVEDataset` and `CPEDataset` instances take a lot of memory." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Automatically match CPEs and CVEs\n", - "dset.compute_cpe_heuristics()\n", - "dset.compute_related_cves()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Create new dataset and fully process it\n", - "\n", - "The following piece of code roughly corresponds to `$ cc-certs all` CLI command -- it fully processes the CC pipeline. This will create a folder in current working directory where the outputs will be stored. \n", - "\n", - "*Warning*: It's not good idea to run this from notebook. It may take several hours to finnish. We recommend using `from_web_latest()` or turning this into a Python script." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dset = CCDataset()\n", - "dset.get_certs_from_web()\n", - "dset.process_auxillary_datasets()\n", - "dset.download_all_artifacts()\n", - "dset.convert_all_pdfs()\n", - "dset.analyze_certificates()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3.8.13 ('venv': venv)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.8.13 (default, Jul 27 2022, 12:09:23) \n[Clang 13.1.6 (clang-1316.0.21.2.3)]" - }, - "orig_nbformat": 4, - "vscode": { - "interpreter": { - "hash": "a5b8c5b127d2cfe5bc3a1c933e197485eb9eba25154c3661362401503b4ef9d4" - } - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} -- cgit v1.3.1