From patchwork Thu Jul 11 06:04:15 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Sangorrin X-Patchwork-Id: 11039319 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 6A143912 for ; Thu, 11 Jul 2019 06:14:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4C52F28A6C for ; Thu, 11 Jul 2019 06:14:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 40AB028A73; Thu, 11 Jul 2019 06:14:33 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id B703328A6C for ; Thu, 11 Jul 2019 06:14:32 +0000 (UTC) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 4E0A04B7A; Thu, 11 Jul 2019 06:14:32 +0000 (UTC) X-Original-To: cip-dev@lists.cip-project.org Delivered-To: cip-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 9B05C4B73 for ; Thu, 11 Jul 2019 06:04:28 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mo-csw.securemx.jp (mo-csw1514.securemx.jp [210.130.202.153]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 5C0118A7 for ; Thu, 11 Jul 2019 06:04:26 +0000 (UTC) Received: by mo-csw.securemx.jp (mx-mo-csw1514) id x6B64KeY023748; Thu, 11 Jul 2019 15:04:20 +0900 X-Iguazu-Qid: 34tIVWg40e5jlCTwl1 X-Iguazu-QSIG: v=2; s=0; t=1562825059; q=34tIVWg40e5jlCTwl1; m=FBd2kEZ4rKIn+iLeI1SZeSwVr6d2KsdGqBJhleU/00o= Received: from imx2.toshiba.co.jp (imx2.toshiba.co.jp [106.186.93.51]) by relay.securemx.jp (mx-mr1513) id x6B64IMn015978; Thu, 11 Jul 2019 15:04:19 +0900 Received: from enc01.localdomain ([106.186.93.100]) by imx2.toshiba.co.jp with ESMTP id x6B64Iba022889; Thu, 11 Jul 2019 15:04:18 +0900 (JST) Received: from hop001.toshiba.co.jp ([133.199.164.63]) by enc01.localdomain with ESMTP id x6B64IO9025436; Thu, 11 Jul 2019 15:04:18 +0900 From: Daniel Sangorrin To: ben.hutchings@codethink.co.uk Date: Thu, 11 Jul 2019 15:04:15 +0900 X-TSB-HOP: ON Message-Id: <20190711060415.17484-2-daniel.sangorrin@toshiba.co.jp> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190711060415.17484-1-daniel.sangorrin@toshiba.co.jp> References: <20190711060415.17484-1-daniel.sangorrin@toshiba.co.jp> Cc: cip-dev@lists.cip-project.org Subject: [cip-dev] [cip-kernel-sec][Quickstart v2] docs: add a quickstart with practical information X-BeenThere: cip-dev@lists.cip-project.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: cip-dev-bounces@lists.cip-project.org Errors-To: cip-dev-bounces@lists.cip-project.org X-Virus-Scanned: ClamAV using ClamSMTP Although the README already contains all the information that users may need, there are some bits of know-how that are better expressed through a step-by-step quickstart or tutorial. This files tries to fill that gap. Signed-off-by: Daniel Sangorrin --- QUICKSTART.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 QUICKSTART.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..c79af41 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,132 @@ +# Quickstart + +## Overview + +This project tracks the status of CVEs in mainline and stable kernels. Each CVE is described in YAML format that includes data such as: + +``` +$ cat issues/CVE-2019-1999.yml +description: 'binder: fix race between munmap() and direct reclaim' +references: +- https://source.android.com/security/bulletin/2019-02-01 +comments: + Debian-bwh: |- + Introduced in 4.14 by f2517eb76f1f "android: binder: Add global lru + shrinker to binder". Backports of the fix to stable have incorrect + metadata. + bwh: Backports to stable have incorrect metadata +introduced-by: + mainline: [f2517eb76f1f2f7f89761f9db2b202e89931738c] +fixed-by: + linux-4.14.y: [33c6b9ca70a8b066a613e2a3d0331ae8f82aa31a] + linux-4.19.y: [6bf7d3c5c0c5dad650bfc4345ed553c18b69d59e] + linux-5.0.y: [bbb19ca082ce27ce60ca65be016a951806ea947c] + mainline: [5cec2d2e5839f9c0fec319c523a911e0a7fd299f] +``` + +## Quickstart + +Clone `cip-kernel-sec` and install its dependencies: + +``` +$ git clone https://gitlab.com/cip-project/cip-kernel/cip-kernel-sec +$ cd cip-kernel-sec/ +$ sudo apt install python3-yaml python3-html5lib python3-cherrypy3 python3-jinja2 +``` + +Prepare kernel remote repositories according to `conf/remotes.yml`: + +``` +$ ./scripts/prepare_remotes.py +``` + +Alternatively, you can do that manually: + +``` +$ mkdir ../kernel +$ cd ../kernel +$ git remote add torvalds https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git +$ git remote add stable https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git +$ git remote add cip https://git.kernel.org/pub/scm/linux/kernel/git/cip/linux-cip.git +$ cd ../cip-kernel-sec +``` + +Download CVE information from [Debian] (https://salsa.debian.org/kernel-team/kernel-sec.git), [Ubuntu] (https://git.launchpad.net/ubuntu-cve-tracker) and Stable: + +``` + +$ ./scripts/import_debian.py + -> import/debian +$ ./scripts/import_ubuntu.py + -> import/ubuntu +$ ./scripts/import_stable.py + -> import/stable_branches.yml +``` + +Check issues that affect a linux-cip branch: + +``` +$ ./scripts/report_affected.py linux-4.4.y +``` + +You can show a short description on your report: + +``` +$ ./scripts/report_affected.py --show-description linux-4.4.y +``` + +Check issues that affect a tag: + +``` +$ ./scripts/report_affected.py v4.4.181-cip33 +``` + +Browse kernel branches and issues interactively: + +``` +$ ./scripts/webview.py +$ firefox http://localhost:8080 +``` + +[Note] Use Ctr-c to stop the `webview.py` script. + +## Kernel maintainer workflow + +Import or update the latest CVE information: + +``` +$ ./scripts/import_debian.py +$ ./scripts/import_ubuntu.py +$ ./scripts/import_stable.py +``` + +Edit by hand the newly created issues if you see that some imported information is incorrect or there is missing information: + +``` +$ vi issues/CVE-xx.yml +``` + +Validate the issue files against the YAML schema. + +``` +$ ./scripts/validate.py +``` + +YAML allows the same thing to be written in different ways, e.g. bracketed vs bulleted lists. Use `cleanup.py` to make the syntax and ordering of items consistent with the importers, to reduce "noise" in diffs: + +``` +$ ./scripts/cleanup.py +``` + +Check if the current issues: + +``` +$ ./scripts/report_affected.py +``` + +## Changelog + +- 20190614: First version +- 20190618: Add workflow information provided by Ben +- 20190711: Add tag reporting +