diff --git a/.github/ISSUE_TEMPLATE/01-proposal.md b/.github/ISSUE_TEMPLATE/01-proposal.md index 0a538d914e..05f3163500 100644 --- a/.github/ISSUE_TEMPLATE/01-proposal.md +++ b/.github/ISSUE_TEMPLATE/01-proposal.md @@ -8,4 +8,3 @@ labels: i/proposal Our proposal process is documented here: https://docs.scion.org/en/latest/dev/contribute.html#change-proposal-process --> - diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..7be2f0b209 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,27 @@ +{ + "globs": ["**/*.md"], + "ignores": [ + "**/venv/**", + "**/_build/**", + "**/node_modules/**", + "licenses/data/**", + "tools/coremark/LICENSE.md" + ], + "config": { + "default": true, + "MD007": { + "indent": 4 + }, + "MD013": { + "line_length": 100, + "code_blocks": false, + "tables": false + }, + "MD024": { + "siblings_only": true + } + }, + "outputFormatters": [ + [ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ] + ] +} diff --git a/Makefile b/Makefile index 638e6ad1ea..cca8256d3c 100644 --- a/Makefile +++ b/Makefile @@ -153,5 +153,5 @@ lint-doc: lint-doc-mdlint lint-doc-mdlint: $(info ==> $@) - @FILES=$$(find -type f -iname '*.md' -not -path "./private/mgmtapi/tools/node_modules/*" -not -path "./.github/**/*" | grep -vf tools/md/skipped); \ - docker run --rm -v ${PWD}:/data -v ${PWD}/tools/md/mdlintstyle.rb:/style.rb $$(docker build -q tools/md) $${FILES} -s /style.rb + @if [ -t 1 ]; then tty=true; else tty=false; fi; \ + tools/quiet docker run --tty=$$tty --rm -v ${PWD}:/workdir davidanson/markdownlint-cli2:v0.12.1 diff --git a/doc/.markdownlint-cli2.jsonc b/doc/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..d3abaacd35 --- /dev/null +++ b/doc/.markdownlint-cli2.jsonc @@ -0,0 +1,11 @@ +{ + "extends": "../.markdownlint-cli2.jsonc", + "config": { + "MD033": { + "allowed_elements": [ + "a", + "sub" + ] + } + } +} diff --git a/doc/dev/design/BeaconService.md b/doc/dev/design/BeaconService.md index ac9e514447..1d21ecd71d 100644 --- a/doc/dev/design/BeaconService.md +++ b/doc/dev/design/BeaconService.md @@ -4,7 +4,8 @@ * Status: **outdated** --- -⚠️ **NOTE** ⚠️
+⚠️ **NOTE** ⚠️ + Outdated contents! This document is kept for historical purpose. --- diff --git a/doc/dev/design/ColibriService.md b/doc/dev/design/ColibriService.md index cf04705045..cc8b7bd27a 100644 --- a/doc/dev/design/ColibriService.md +++ b/doc/dev/design/ColibriService.md @@ -9,7 +9,8 @@ * Discussion at: [#3653](https://github.com/scionproto/scion/issues/3653), [#3794](https://github.com/scionproto/scion/issues/3794) --- -⚠️ **NOTE** ⚠️
+⚠️ **NOTE** ⚠️ + Outdated contents! This document is kept for historical purpose. --- @@ -91,7 +92,7 @@ next AS after ASi in the path of the reservation. 1. The *COS* store is queried to admit the segment reservation. 1. The store decides the admission for the reservation (how much bandwidth). It uses the - _traffic_matrix_ from the configuration package. + *traffic_matrix* from the configuration package. 1. The store saves an intermediate reservation entry in the DB. 1. If this AS is the last one in the path, the *COS* store saves the reservation as final and notifies the previous AS in the path with a reservation response. @@ -105,7 +106,7 @@ ASes. Whenever that configuration changes, the service should be notified. 1. The service triggers the creation of a new segment reservation at boot time and whenever the segment reservation configuration file changes. 1. The service reads the configuration file and creates a segment reservation request per each entry. - * The path used in the request must be obtained using the _path predicate_ in the configuration. + * The path used in the request must be obtained using the *path predicate* in the configuration. 1. The store in the *COS* saves the intermediate request and sends the request to the next AS in the path. 1. If there is a timeout, this store will send a cleanup request to the next AS in the path. diff --git a/doc/dev/design/EPIC.md b/doc/dev/design/EPIC.md index 4e69bd5036..ae54d988a2 100644 --- a/doc/dev/design/EPIC.md +++ b/doc/dev/design/EPIC.md @@ -102,7 +102,7 @@ meaningful level of security: ### Example -![](fig/EPIC/path-type-filtering-small.png). +![path type filtering figure](fig/EPIC/path-type-filtering-small.png). Here, AS 6 is the AS protected by the hidden path (blue lines). The hidden path terminates at AS 6 (represented by black dot), so AS 6 @@ -182,8 +182,7 @@ not apply any filtering for traffic from interface 2 to interface 1. There are two main applications for EPIC-HP: - -### Highly Secure Hidden Paths +### Highly Secure Hidden Paths The last and penultimate ASes on the hidden path only allow EPIC-HP traffic on the interface pairs that affect the hidden path. @@ -203,8 +202,7 @@ packets towards hosts in other ASes, but that those hosts can not send a response back if they do not have the necessary authenticators. - -### DoS-Secure Hidden Paths +### DoS-Secure Hidden Paths The last and penultimate ASes on the hidden path allow EPIC-HP and other path types simultaneously, but prioritize traffic using the @@ -222,9 +220,9 @@ authenticators to send back EPIC-HP traffic. ## References -[1] -M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020)
-EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet
+[^1] +M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020)\ +EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet\ Proceedings of the USENIX Security Symposium [[Link]](https://netsec.ethz.ch/publications/papers/Legner_Usenix2020_EPIC.pdf) @@ -233,7 +231,7 @@ Design Document for the Hidden Path Infrastructure [[Link]](/hidden-paths) [3] -T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017)
-The Case for In-Network Replay Suppression
+T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017)\ +The Case for In-Network Replay Suppression\ Proceedings of the ACM Asia Conference on Computer and Communications Security [[Link]](https://netsec.ethz.ch/publications/papers/replay2017.pdf) diff --git a/doc/dev/design/PathPolicy.md b/doc/dev/design/PathPolicy.md index 0e108637ab..1d8fa91002 100644 --- a/doc/dev/design/PathPolicy.md +++ b/doc/dev/design/PathPolicy.md @@ -42,10 +42,10 @@ Examples: A policy is defined by a policy object. It can have the following attributes: -- [`extends`](#Extends) (list of extended policies) -- [`acl`](#ACL) (list of HPs, preceded by `+` or `-`) -- [`sequence`](#Sequence) (space separated list of HPs, may contain operators) -- [`options`](#Options) (list of option policies) +- [`extends`](#extends) (list of extended policies) +- [`acl`](#acl) (list of HPs, preceded by `+` or `-`) +- [`sequence`](#sequence) (space separated list of HPs, may contain operators) +- [`options`](#options) (list of option policies) - `weight` (importance level, only valid under `options`) - `policy` (a policy object) @@ -75,8 +75,8 @@ Planned: - `-` (deny predicate) The ACL can be used to deny (blacklist) or allow (whitelist) ISDs, ASes and IFs. A deny entry is of -the following form `- ISD-AS#IF`, where the second part is a [HP](#HP). If a deny entry matches any -hop on a path, the path is not allowed. +the following form `- ISD-AS#IF`, where the second part is a [Hop Predicate](#hop-predicate-hp). +If a deny entry matches any hop on a path, the path is not allowed. An allow entry uses `+` with a HP, ie. `+ ISD-AS#IF`. For a path to be allowed, every hop of the path must be allowed by the ACL. When using allow and deny entries in the same ACL, the first @@ -113,7 +113,7 @@ Planned: - `!` (logical NOT) - `&` (logical AND) -The sequence is a string of space separated HPs. The [operators](#Operators) can be used for +The sequence is a string of space separated HPs. The [operators](#operators) can be used for advanced interface sequences. The following example specifies a path from any interface in AS _1-ff00:0:133_ to two subsequent @@ -215,7 +215,8 @@ third option which denies only hops in AS _1-ff00:0:133_, is used. ## Path policies in path lookup -⚠️ **NOTE** ⚠️
+⚠️ **NOTE** ⚠️ + Outdated contents! This section is kept for historical purpose. --- diff --git a/doc/dev/design/PathService.md b/doc/dev/design/PathService.md index ab54dd7317..f2b0a4d350 100644 --- a/doc/dev/design/PathService.md +++ b/doc/dev/design/PathService.md @@ -4,7 +4,8 @@ * Status: **outdated** --- -⚠️ **NOTE** ⚠️
+⚠️ **NOTE** ⚠️ + Outdated contents! This document is kept for historical purpose. --- @@ -15,11 +16,11 @@ The path service is implemented as part of the control server. We use the messenger to register request handlers. The following requests are handled: -* __Path Registration:__ A handler for the path-registration request, only in core ASes. -* __Path Requests:__ Two different types of `SegReq` are handled by separate handlers: +* **Path Registration:** A handler for the path-registration request, only in core ASes. +* **Path Requests:** Two different types of `SegReq` are handled by separate handlers: * local requests, coming over TCP. * requests from other path servers, over SCION/QUIC, only in core ASes. -* __Path Revocation:__ A handler for the path-revocation message +* **Path Revocation:** A handler for the path-revocation message ## Deletion of Expired Path Segments and Revocations diff --git a/doc/manuals/control.rst b/doc/manuals/control.rst index 5855abfd18..c96849babc 100644 --- a/doc/manuals/control.rst +++ b/doc/manuals/control.rst @@ -252,7 +252,7 @@ considers the following options. - use the `netsys-lab/scion-ca `_ SCION CA based on `smallstep's step-ca `_, - ask SCION vendors for proprietary CA implementations and offerings, - - plug in your own CA service implementing the :file-ref:`spec/ca.gen.yaml` API. + - plug in your own CA service implementing the :file-ref:`spec/ca.gen.yml` API. .. option:: ca.service.address = diff --git a/tools/md/Dockerfile b/tools/md/Dockerfile deleted file mode 100644 index 9dda870a7f..0000000000 --- a/tools/md/Dockerfile +++ /dev/null @@ -1,12 +0,0 @@ -FROM alpine:3.10 - -RUN apk update && \ - apk add --no-cache ruby ruby-json && \ - gem install --no-rdoc --no-ri -v 0.9.0 mdl - -RUN mkdir /data - -WORKDIR /data - -ENTRYPOINT ["mdl"] -CMD ["--help"] diff --git a/tools/md/mdlintstyle.rb b/tools/md/mdlintstyle.rb deleted file mode 100644 index 4e6114f509..0000000000 --- a/tools/md/mdlintstyle.rb +++ /dev/null @@ -1,7 +0,0 @@ -all -rule 'MD013', :line_length => 100 -rule 'MD013', :code_blocks => false -rule 'MD013', :tables => false -rule 'MD007', :indent => 4 # see https://github.com/markdownlint/markdownlint/issues/139 -rule 'MD024', :allow_different_nesting => true -exclude_rule 'MD033' diff --git a/tools/md/skipped b/tools/md/skipped deleted file mode 100644 index 3e1c5d2276..0000000000 --- a/tools/md/skipped +++ /dev/null @@ -1,4 +0,0 @@ -^\./docker/_build/ -^\./licenses/data -^\./rules_openapi/tools/ -^\./tools/coremark/LICENSE.md