From 466a12a788623f3b910c176333f1098a59620f1e Mon Sep 17 00:00:00 2001
From: wunder957 <141890183+wunder957@users.noreply.github.com>
Date: Mon, 14 Aug 2023 16:29:25 +0800
Subject: [PATCH] Add some docs (#3)
* Add some docs
* Add intro
* Update docs
* Add link to docs
---
DEVELOP.md | 33 ++++++
README.md | 90 +++++++++++----
README_en.md | 80 +++++++++++++
RELEASE.md | 17 ++-
docker/Dockerfile | 4 +-
docker/Dockerfile.bcc | 20 ----
docs/Makefile | 20 ----
docs/conf.py | 154 --------------------------
docs/design/README.md | 0
docs/design/image/architecture.png | Bin 0 -> 667 bytes
docs/design/src/architecture.drawio | 0
docs/how-to/work-in-katacontainers.md | 0
docs/index.rst | 14 ---
docs/make.bat | 36 ------
docs/usage.rst | 7 --
15 files changed, 200 insertions(+), 275 deletions(-)
create mode 100644 DEVELOP.md
create mode 100644 README_en.md
delete mode 100644 docker/Dockerfile.bcc
delete mode 100644 docs/Makefile
delete mode 100755 docs/conf.py
create mode 100644 docs/design/README.md
create mode 100644 docs/design/image/architecture.png
create mode 100644 docs/design/src/architecture.drawio
create mode 100644 docs/how-to/work-in-katacontainers.md
delete mode 100644 docs/index.rst
delete mode 100644 docs/make.bat
delete mode 100644 docs/usage.rst
diff --git a/DEVELOP.md b/DEVELOP.md
new file mode 100644
index 0000000..348a2e7
--- /dev/null
+++ b/DEVELOP.md
@@ -0,0 +1,33 @@
+# Code Style and Lint
+
+We use [black](https://github.com/psf/black) as the code formatter, the best way to use it is to install the pre-commit hook, it will automatically format the code before each commit
+
+Install pre-commit before commit
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+Pre-commit will automatically format the code before each commit, It can also be executed manually on all files
+
+```bash
+pre-commit run --all-files
+```
+
+# Install Locally with Test Dependencies
+
+```bash
+pip install -e .[test]
+```
+
+# Unit-test
+
+We use pytest to write unit tests, and use pytest-cov to generate coverage reports
+
+```bash
+pytest -v # Run unit-test
+pytest --cov=duetector --cov-report=html # Generate coverage reports
+```
+
+Run unit-test before PR, **ensure that new features are covered by unit tests**
diff --git a/README.md b/README.md
index 8e10e69..116b869 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,84 @@
-
-
-
-
-
+duetector🔍: 基于eBPF的数据使用控制探测器
+
+
+
+
+
+
+
-# duetector
+
+中文 | English
+
-duetector🔍: Data Usage eBPF detector
+## 简介
-## Install
+> duetector是DataUCON项目中的组件之一，DataUCON项目旨在为数据使用控制提供支持。[了解DataUCON](https://dataucon.idslab.io/)。
-`pip install duetector`
+duetector🔍是一个基于eBPF的数据使用控制探测器，它可以在Linux内核中对数据使用行为进行探测，从而为数据使用控制提供支持。
-## Usage
+
-## Develop
+在[ABAUC控制模型](https://github.com/hitsz-ids/dataucon)当中，duetector可作为PIP（Policy Information Point）来获取数据使用行为，从而为PDP（Policy Decision Point）提供数据使用行为的信息。
-Install pre-commit before commit
+## 目录
-```
-pip install pre-commit
-pre-commit install
-```
+- [主要特性](#主要特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [API文档](#API文档)
+- [维护者](#维护者)
+- [如何贡献](#如何贡献)
+- [许可证](#许可证)
-Install package locally
+## 主要特性
+TBD
+
+TODO: 特性和[对应的内核配置](https://github.com/iovisor/bcc/blob/master/docs/kernel_config.md)
+
+## 安装
+
+代码通过Pypi分发，你可以通过以下命令安装
+
+```bash
+pip install duetector
```
-pip install -e .[test]
-```
-Run unit-test before PR, **ensure that new features are covered by unit tests**
+目前，代码依赖[BCC](https://github.com/iovisor/bcc)对eBPF代码进行即时编译，推荐[安装最新的BCC编译器](https://github.com/iovisor/bcc/blob/master/INSTALL.md)
+
+或使用我们提供的Docker镜像
+```bash
+docker pull dataucon/duetector:latest
```
-pytest -v
+
+预发布版本将不会更新到 `latest`上，您可以指定tag进行拉取，如 `v0.1.0`
+
+```bash
+docker pull dataucon/duetector:v0.1.0
```
+
+## 快速开始
+
+TBD
+
+更多文档和例子可以在[这里]("./docs")找到。
+
+## API文档
+
+TBD
+
+## 维护者
+
+本项目由**哈尔滨工业大学（深圳）数据安全研究院**发起，若您对本项目以及DataUCON项目感兴趣并愿意一起完善它，欢迎加入我们的开源社区。
+
+## 如何贡献
+
+非常欢迎你的加入！[提一个 Issue](https://github.com/hitsz-ids/duetector/issues/new) 或者提交一个 Pull Request。
+
+开发环境配置和其他注意事项请参考[开发者文档](./DEVELOP.md)。
+
+## 许可证
+
+本项目使用 Apache-2.0 license，有关协议请参考[LICENSE](https://github.com/hitsz-ids/duetector/blob/main/LICENSE)。
diff --git a/README_en.md b/README_en.md
new file mode 100644
index 0000000..a1d464b
--- /dev/null
+++ b/README_en.md
@@ -0,0 +1,80 @@
+duetector🔍: Data Usage eBPF detector
+
+
+
+
+
+
+
+
+
+中文 | English
+
+
+## Introduction
+
+> duetector is one of the components in the DataUCON project, which is designed to provide support for data usage control. [Intro DataUCON](https://dataucon.idslab.io/).
+
+duetector🔍 is an eBPF-based data usage control probe that provides support for data usage control by probing for data usage behavior in the Linux kernel.
+
+In the [ABAUC control model](https://github.com/hitsz-ids/dataucon), duetector can be used as a PIP (Policy Information Point) to obtain data usage behavior, so as to provide information about data usage behavior for PDP (Policy Decision Point). Provide information on data usage behavior to PDP (Policy Decision Point).
+
+## Table of Contents
+
+- [Features](#Features)
+- [Installation](#Installation)
+- [Quick Start](#quick-start)
+- [API](#API)
+- [Maintainers](#Maintainers)
+- [contribute](#contribute)
+- [License](#License)
+
+## Feature
+
+TBD
+
+TODO: Features and corresponding [kernel config](https://github.com/iovisor/bcc/blob/master/docs/kernel_config.md)
+
+## Installation
+
+The code is distributed via Pypi, and you can install it with the following command
+
+```bash
+pip install duetector
+```
+
+Currently, the code relies on [BCC](https://github.com/iovisor/bcc) for on-the-fly compilation of eBPF code, we recommend [installing the latest BCC compiler](https://github.com/iovisor/bcc/blob/master/INSTALL.md)
+
+Or use the Docker image that we provide
+
+```bash
+docker pull dataucon/duetector:latest
+```
+
+Pre-releases will not be updated on `latest`, you can specify the tag to pull, e.g. `v0.1.0`
+
+```bash
+docker pull dataucon/duetector:v0.1.0
+```
+
+## Quick start
+
+TBD
+
+## API documentation
+
+TBD
+
+## Maintainers
+
+This project is initiated by **Institute of Data Security, Harbin Institute of Technology (Shen Zhen)**, if you are interested in this project and [DataUCON](https://dataucon.idslab.io/) project and willing to work together to improve it, welcome to join our open source community.
+
+## How to contribute
+
+You are very welcome to join! [Raise an Issue](https://github.com/hitsz-ids/duetector/issues/new) or submit a Pull Request.
+
+Please refer to [Developer Documentation](./DEVELOP.md).
+
+## License
+
+This project uses Apache-2.0 license, please refer to [LICENSE](https://github.com/hitsz-ids/duetector/blob/main/LICENSE).
diff --git a/RELEASE.md b/RELEASE.md
index 9734c74..2c0dd9d 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -11,8 +11,7 @@ packages. Before generating a package, we first need to install `build`.
pip install build twine hatch
```
-Bump the version using `hatch`. By default this will create a tag.
-See the docs on [hatch-nodejs-version](https://github.com/agoose77/hatch-nodejs-version#semver) for details.
+Bump the version using `hatch`.
```bash
hatch version
@@ -32,3 +31,17 @@ Then to upload the package to PyPI, do:
```bash
twine upload dist/*
```
+
+## Github Action release
+
+### Python package and Docker image
+
+The version number needs to be changed manually before proceeding with the release.
+
+```bash
+hatch version
+```
+
+Once there is a release, [Github Action](https://github.com/hitsz-ids/duetector/actions/workflows/publish.yml) will automatically publish docker image based on the `tag.`
+
+If it's a pre-release release, the `latest` version of the image will not be released.
diff --git a/docker/Dockerfile b/docker/Dockerfile
index e63cf83..28c1e55 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -1,5 +1,7 @@
+# https://github.com/hitsz-ids/dataucon/blob/main/docker/Dockerfile.bcc
+
ARG BCC_VERSION=v0.28.0
FROM dataucon/ubuntu-bcc:${BCC_VERSION}
-RUN pip install duetector
+RUN pip install duetector --no-cache-dir
diff --git a/docker/Dockerfile.bcc b/docker/Dockerfile.bcc
deleted file mode 100644
index 0e5664f..0000000
--- a/docker/Dockerfile.bcc
+++ /dev/null
@@ -1,20 +0,0 @@
-FROM ubuntu:22.04
-ARG BCC_VERSION=v0.28.0
-
-RUN apt-get update && apt-get install -y zip bison build-essential cmake flex git libedit-dev \
- libllvm14 llvm-14-dev libclang-14-dev python3 python3-pip python-is-python3 zlib1g-dev libelf-dev libfl-dev python3-setuptools \
- liblzma-dev libdebuginfod-dev arping netperf iperf \
- && rm -rf /var/lib/apt/lists/*
-
-RUN git clone --depth 1 --branch ${BCC_VERSION} https://github.com/iovisor/bcc.git &&\
- mkdir bcc/build; cd bcc/build &&\
- cmake .. &&\
- make -j$(nproc) &&\
- make install &&\
- cmake -DPYTHON_CMD=python3 .. # build python3 binding &&\
- pushd src/python/ &&\
- make &&\
- make install &&\
- popd
-
-# BCC_VERSION=v0.28.0;docker build -t dataucon/ubuntu-bcc:${BCC_VERSION} -f docker/Dockerfile.bcc --build-arg BCC_VERSION=${BCC_VERSION} .
diff --git a/docs/Makefile b/docs/Makefile
deleted file mode 100644
index 0c5084e..0000000
--- a/docs/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = python -msphinx
-SPHINXPROJ = duetector
-SOURCEDIR = .
-BUILDDIR = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
deleted file mode 100755
index ef3bbdc..0000000
--- a/docs/conf.py
+++ /dev/null
@@ -1,154 +0,0 @@
-#!/usr/bin/env python
-#
-# duetector documentation build configuration file, created by
-# sphinx-quickstart on Fri Jun 9 13:47:02 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another
-# directory, add these directories to sys.path here. If the directory is
-# relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-#
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath(".."))
-
-import duetector
-
-# -- General configuration ---------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
-project = "duetector"
-copyright = "2023, hitsz-ids"
-author = "hitsz-ids"
-
-# The version info for the project you're documenting, acts as replacement
-# for |version| and |release|, also used in various other places throughout
-# the built documents.
-#
-# The short X.Y version.
-version = duetector.__version__
-# The full version, including alpha/beta/rc tags.
-release = duetector.__version__
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
-# -- Options for HTML output -------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-#
-html_theme = "alabaster"
-
-# Theme options are theme-specific and customize the look and feel of a
-# theme further. For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
-
-# -- Options for HTMLHelp output ---------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "duetectordoc"
-
-
-# -- Options for LaTeX output ------------------------------------------
-
-latex_elements = {
- # The paper size ('letterpaper' or 'a4paper').
- #
- # 'papersize': 'letterpaper',
- # The font size ('10pt', '11pt' or '12pt').
- #
- # 'pointsize': '10pt',
- # Additional stuff for the LaTeX preamble.
- #
- # 'preamble': '',
- # Latex figure (float) alignment
- #
- # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto, manual, or own class]).
-latex_documents = [
- (master_doc, "duetector.tex", "duetector Documentation", "hitsz-ids", "manual"),
-]
-
-
-# -- Options for manual page output ------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "duetector", "duetector Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output ----------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-texinfo_documents = [
- (
- master_doc,
- "duetector",
- "duetector Documentation",
- author,
- "duetector",
- "One line description of project.",
- "Miscellaneous",
- ),
-]
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/design/image/architecture.png b/docs/design/image/architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..d570e9b495c6c1f3af3fe4c64c7c84d50bb214c1
GIT binary patch
literal 667
zcmZ`%O;5rw7%n6lgK{)6#>7)Eo>(U!7ZYIP;~)_*fg{aYwwjG%nSvg@@mDzTD?E7e
z=8y1S*sdL9F(&KQ_u2EjPv5ui`o7mL7S0O*fMU1f4CFVb*3qGSU!H!fRj?Se8({l&
z@dH5qHg?Bxw3@Pz0%$k&4%)8V6NY_(BZx|jK-+-`jY%H|o)~%Ffc769_i6lsBrF*-
z98t}IZWY#>>Omz-F6h=^-GYs>A|`pGRa@YBaK{M^C4sE8uzX$9xyY*qEE`oc;*0bI
zGNZCnz>vKeORHqiXGZA4h&2>*9>#2*1wB5SQ7_IAu@HQjrA>Kg>Nc)(?5B=8y8?zD
z4*#MfM&dvl+@R{7-J#46QfI4TDvoeUHkB*_O!!jk6DVn%;9N@GKp~O&v={ThEZdA%wn-e)!$6crXa5nNLAP>L+$Zftq`w|9S
Kx94mdllNb4A*)~j
literal 0
HcmV?d00001
diff --git a/docs/design/src/architecture.drawio b/docs/design/src/architecture.drawio
new file mode 100644
index 0000000..e69de29
diff --git a/docs/how-to/work-in-katacontainers.md b/docs/how-to/work-in-katacontainers.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index c2d8b7f..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-Welcome to duetector's documentation!
-======================================
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
- usage
-
-Indices and tables
-==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
deleted file mode 100644
index 8c9675f..0000000
--- a/docs/make.bat
+++ /dev/null
@@ -1,36 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=python -msphinx
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-set SPHINXPROJ=duetector
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The Sphinx module was not found. Make sure you have Sphinx installed,
- echo.then set the SPHINXBUILD environment variable to point to the full
- echo.path of the 'sphinx-build' executable. Alternatively you may add the
- echo.Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
- exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
diff --git a/docs/usage.rst b/docs/usage.rst
deleted file mode 100644
index e1d6842..0000000
--- a/docs/usage.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-=====
-Usage
-=====
-
-To use duetector in a project::
-
- import duetector