Add some docs (hitsz-ids#3)

* Add some docs * Add intro * Update docs * Add link to docs
wunder957 · Aug 14, 2023 · 466a12a · 466a12a
1 parent f40039b
commit 466a12a
Show file tree

Hide file tree

Showing 15 changed files with 200 additions and 275 deletions.
diff --git a/DEVELOP.md 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
@@ -1,36 +1,84 @@
-![](https://img.shields.io/github/license/hitsz-ids/duetector)
-![](https://img.shields.io/github/v/release/hitsz-ids/duetector)
-![](https://img.shields.io/pypi/dm/duetector)
-![](https://img.shields.io/github/last-commit/hitsz-ids/duetector)
-![](https://img.shields.io/pypi/pyversions/duetector)
+<h2 align="center">duetector🔍: 基于eBPF的数据使用控制探测器</h2>
+<p align="center">
+<a href="https://github.com/hitsz-ids/duetector/actions"><img alt="Actions Status" src="https://github.com/hitsz-ids/duetector/actions/workflows/python-package.yml/badge.svg"></a>
+<a href="https://github.com/hitsz-ids/duetector/blob/main/LICENSE"><img alt="LICENSE" src="https://img.shields.io/github/license/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector/releases/"><img alt="Releases" src="https://img.shields.io/github/v/release/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector"><img alt="Last Commit" src="https://img.shields.io/github/last-commit/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector"><img alt="Python version" src="https://img.shields.io/pypi/pyversions/duetector"></a>
+</p>
 
-# duetector
+<p align="center">
+<a href="./README.md">中文</a> | <a href="./README_en.md">English</a>
+</p>
 
-duetector🔍: Data Usage eBPF detector
+## 简介
 
-## Install
+> duetector是DataUCON项目中的组件之一，DataUCON项目旨在为数据使用控制提供支持。[了解DataUCON](https://dataucon.idslab.io/)。
 
-`pip install duetector`
+duetector🔍是一个基于eBPF的数据使用控制探测器，它可以在Linux内核中对数据使用行为进行探测，从而为数据使用控制提供支持。
 
-## Usage
+<!-- 这里需要补充ABAUC相关文档，然后替换链接 -->
 
-## 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
@@ -0,0 +1,80 @@
+<h2 align="center">duetector🔍: Data Usage eBPF detector </h2>
+<p align="center">
+<a href="https://github.com/hitsz-ids/duetector/actions"><img alt="Actions Status" src="https://github.com/hitsz-ids/duetector/actions/workflows/python-package.yml/badge.svg"></a>
+<a href="https://github.com/hitsz-ids/duetector/blob/main/LICENSE"><img alt="LICENSE" src="https://img.shields.io/github/license/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector/releases/"><img alt="Releases" src="https://img.shields.io/github/v/release/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector"><img alt="Last Commit" src="https://img.shields.io/github/last-commit/hitsz-ids/duetector"></a>
+<a href="https://github.com/hitsz-ids/duetector"><img alt="Python version" src="https://img.shields.io/pypi/pyversions/duetector"></a>
+</p>
+
+<p align="center">
+<a href="./README.md">中文</a> | <a href="./README_en.md">English</a>
+</p>
+
+## 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
@@ -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 <new-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 <new-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
@@ -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
diff --git a/docs/Makefile b/docs/Makefile