| 1 |
# corasdiagram |
| 2 |
|
| 3 |
`corasdiagram` is a LaTeX package for authoring CORAS diagrams with reusable |
| 4 |
notation macros, package-managed icons, semantic diagram environments, and |
| 5 |
high-level analysis tables. |
| 6 |
|
| 7 |
The package currently supports the five basic CORAS diagram families: |
| 8 |
|
| 9 |
- asset diagrams |
| 10 |
- threat diagrams |
| 11 |
- risk diagrams |
| 12 |
- treatment diagrams |
| 13 |
- treatment overview diagrams |
| 14 |
|
| 15 |
It also supports high-level analysis risk tables with CORAS header icons. |
| 16 |
|
| 17 |
For narrow layouts such as a side-by-side `minipage` in Overleaf, the high-level |
| 18 |
analysis table accepts `icon scale=<factor>` to shrink the header icon groups, |
| 19 |
for example `icon scale=0.6`. |
| 20 |
|
| 21 |
The supported TeX engines are `pdflatex` and `lualatex`. |
| 22 |
|
| 23 |
## Author and Contact |
| 24 |
|
| 25 |
- Author and maintainer: Fabian Robert Smith |
| 26 |
- Contact email: <[email protected]> |
| 27 |
- Repository and issue tracker: |
| 28 |
[github.com/smithfabian/corasdiagram](https://github.com/smithfabian/corasdiagram) |
| 29 |
([issues](https://github.com/smithfabian/corasdiagram/issues)) |
| 30 |
|
| 31 |
## How the Project Works |
| 32 |
|
| 33 |
This repository keeps the package source, documentation, regression tests, and |
| 34 |
release tooling in one place. |
| 35 |
|
| 36 |
Canonical sources of truth: |
| 37 |
|
| 38 |
- [`VERSION`](VERSION) is the canonical repository release number. |
| 39 |
- [`tex/latex/corasdiagram/corasdiagram-version.tex`](tex/latex/corasdiagram/corasdiagram-version.tex) |
| 40 |
is the TeX runtime mirror of that version and must match `VERSION`. |
| 41 |
- the `\ProvidesPackage` date in |
| 42 |
[`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty) |
| 43 |
must match the current release date in [`CHANGELOG.md`](CHANGELOG.md) |
| 44 |
- [`assets/icons-src/`](assets/icons-src) holds the canonical icon sources. |
| 45 |
- [`NOTICE`](NOTICE) records provenance and the upstream MIT notice for the |
| 46 |
vendored icon sources. |
| 47 |
- [`tex/latex/corasdiagram/icons/`](tex/latex/corasdiagram/icons) holds the |
| 48 |
generated runtime icon assets used by the package. |
| 49 |
- [`tests/corasdiagram/snapshots/`](tests/corasdiagram/snapshots) holds the |
| 50 |
committed visual regression baselines. |
| 51 |
- [`ctan/metadata.json`](ctan/metadata.json) holds the committed CTAN metadata |
| 52 |
used by the release tooling. |
| 53 |
|
| 54 |
Workflow map: |
| 55 |
|
| 56 |
- normal development happens on branches and pull requests |
| 57 |
- merges to `main` trigger CI and deploy the documentation site through the |
| 58 |
dedicated `Pages` workflow |
| 59 |
- pushed version tags matching `vX.Y.Z` trigger the `Release` workflow |
| 60 |
- the release workflow verifies that the tag matches `VERSION` and that the |
| 61 |
package header date matches the current `CHANGELOG.md` release date, builds |
| 62 |
the release archive, publishes the GitHub release assets, and waits at the |
| 63 |
`ctan-release` environment before any CTAN upload can continue |
| 64 |
|
| 65 |
For the full contributor runbook, change checklists, and release procedure, see |
| 66 |
[`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 67 |
|
| 68 |
## Repository Layout |
| 69 |
|
| 70 |
The package source lives in [`tex/latex/corasdiagram/`](tex/latex/corasdiagram), |
| 71 |
examples live in [`examples/`](examples), the manual source lives in |
| 72 |
[`docs/`](docs), semantic regression tests live in |
| 73 |
[`tests/corasdiagram/`](tests/corasdiagram), and committed visual baselines |
| 74 |
live in [`tests/corasdiagram/snapshots/`](tests/corasdiagram/snapshots). CTAN |
| 75 |
metadata lives in [`ctan/`](ctan), and the helper scripts used by CI, Pages, |
| 76 |
releases, and local development live in [`tools/`](tools). |
| 77 |
|
| 78 |
## Installation |
| 79 |
|
| 80 |
For local development inside this repository, compile with: |
| 81 |
|
| 82 |
```bash |
| 83 |
TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex |
| 84 |
``` |
| 85 |
|
| 86 |
For a user-level TEXMF installation from a repository checkout, copy |
| 87 |
[`tex/latex/corasdiagram/`](tex/latex/corasdiagram) |
| 88 |
to `~/texmf/tex/latex/corasdiagram/` and refresh the TeX filename database if |
| 89 |
your distribution requires it. |
| 90 |
|
| 91 |
The release workflow also assembles a CTAN-friendly distribution bundle with |
| 92 |
runtime files flattened under `tex/`, documentation under `doc/`, and the |
| 93 |
top-level metadata files such as [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). |
| 94 |
If you are installing from that bundle manually, copy the contents of `tex/` |
| 95 |
into `~/texmf/tex/latex/corasdiagram/`. Once the package is published to CTAN |
| 96 |
or TeX Live, installation can happen through the normal package manager for the |
| 97 |
TeX distribution. |
| 98 |
|
| 99 |
## Using In Your Own Project |
| 100 |
|
| 101 |
The package can be used directly in both Overleaf projects and ordinary local |
| 102 |
LaTeX projects by copying the package file together with its icon assets. |
| 103 |
|
| 104 |
### Overleaf |
| 105 |
|
| 106 |
Upload these from the repository: |
| 107 |
|
| 108 |
- [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty) |
| 109 |
- the full [`tex/latex/corasdiagram/icons/`](tex/latex/corasdiagram/icons) directory |
| 110 |
|
| 111 |
The simplest Overleaf layout is: |
| 112 |
|
| 113 |
```text |
| 114 |
main.tex |
| 115 |
corasdiagram.sty |
| 116 |
icons/ |
| 117 |
corasdiagram-asset.pdf |
| 118 |
corasdiagram-stakeholder.pdf |
| 119 |
corasdiagram-risk.pdf |
| 120 |
... |
| 121 |
``` |
| 122 |
|
| 123 |
Then load the package normally: |
| 124 |
|
| 125 |
```latex |
| 126 |
\usepackage{corasdiagram} |
| 127 |
``` |
| 128 |
|
| 129 |
This works because the package resolves the default icon path relative to the |
| 130 |
location of `corasdiagram.sty`. |
| 131 |
|
| 132 |
If you prefer to keep the package in a subfolder, keep the `icons/` directory |
| 133 |
beside the `.sty` file, for example: |
| 134 |
|
| 135 |
```text |
| 136 |
main.tex |
| 137 |
corasdiagram/ |
| 138 |
corasdiagram.sty |
| 139 |
icons/ |
| 140 |
corasdiagram-asset.pdf |
| 141 |
corasdiagram-stakeholder.pdf |
| 142 |
... |
| 143 |
``` |
| 144 |
|
| 145 |
and load it with: |
| 146 |
|
| 147 |
```latex |
| 148 |
\usepackage{corasdiagram/corasdiagram} |
| 149 |
``` |
| 150 |
|
| 151 |
If your icon directory is somewhere else, set it explicitly: |
| 152 |
|
| 153 |
```latex |
| 154 |
\usepackage[icons-path=coras-assets/icons]{corasdiagram} |
| 155 |
``` |
| 156 |
|
| 157 |
### Local LaTeX Projects |
| 158 |
|
| 159 |
For a normal local project outside this repository, copy the same files into |
| 160 |
your project tree: |
| 161 |
|
| 162 |
```text |
| 163 |
my-project/ |
| 164 |
main.tex |
| 165 |
corasdiagram.sty |
| 166 |
icons/ |
| 167 |
``` |
| 168 |
|
| 169 |
and load the package with: |
| 170 |
|
| 171 |
```latex |
| 172 |
\usepackage{corasdiagram} |
| 173 |
``` |
| 174 |
|
| 175 |
You can also keep the package in a subdirectory and point LaTeX at it in the |
| 176 |
usual way, either by using a TEXMF tree or by loading the package through its |
| 177 |
relative path: |
| 178 |
|
| 179 |
```latex |
| 180 |
\usepackage{vendor/corasdiagram/corasdiagram} |
| 181 |
``` |
| 182 |
|
| 183 |
In that case, keep the `icons/` folder next to the `.sty` file or pass an |
| 184 |
explicit `icons-path=...`. |
| 185 |
|
| 186 |
## Minimal Example |
| 187 |
|
| 188 |
```latex |
| 189 |
\documentclass{article} |
| 190 |
\usepackage{corasdiagram} |
| 191 |
|
| 192 |
\begin{document} |
| 193 |
|
| 194 |
\begin{corasassetdiagram}[x=1cm,y=1cm] |
| 195 |
\corasstakeholder[ |
| 196 |
name=stakeholder, |
| 197 |
scope=asset-scope, |
| 198 |
order=1, |
| 199 |
title={Stakeholder} |
| 200 |
] |
| 201 |
\corasasset[ |
| 202 |
name=asset, |
| 203 |
scope=asset-scope, |
| 204 |
order=1, |
| 205 |
title={Asset} |
| 206 |
] |
| 207 |
\corasindirectasset[ |
| 208 |
name=indirect, |
| 209 |
scope=asset-scope, |
| 210 |
order=2, |
| 211 |
title={Indirect\\Asset} |
| 212 |
] |
| 213 |
\corasscope[ |
| 214 |
name=asset-box, |
| 215 |
scope=asset-scope, |
| 216 |
kind=asset-scope, |
| 217 |
stakeholder=stakeholder, |
| 218 |
stakeholder corner=left |
| 219 |
] |
| 220 |
\corasrelates[from=asset,to=indirect] |
| 221 |
\end{corasassetdiagram} |
| 222 |
|
| 223 |
\end{document} |
| 224 |
``` |
| 225 |
|
| 226 |
## Screenshots |
| 227 |
|
| 228 |
The release workflow publishes the manual PDF and rendered diagram screenshots |
| 229 |
to GitHub Pages and the release artifacts. The committed source tree keeps only |
| 230 |
the package sources and example `.tex` files. |
| 231 |
|
| 232 |
## Public API |
| 233 |
|
| 234 |
The current supported semantic package API is: |
| 235 |
|
| 236 |
- package options: `iconset`, `icons-path` |
| 237 |
- common node keys such as `perspective=before|before-after|after` |
| 238 |
- diagram environments: |
| 239 |
`corasassetdiagram`, `corasthreatdiagram`, `corasriskdiagram`, |
| 240 |
`corastreatmentdiagram`, `corastreatmentoverviewdiagram` |
| 241 |
- high-level analysis table environments: |
| 242 |
`corashighlevelanalysistable`, `corashighlevelrisktable` |
| 243 |
- concept node macros such as `\corasasset`, `\corasindirectasset`, `\corasstakeholder`, |
| 244 |
`\corasrisk`, `\corastreatment`, and the threat/vulnerability/scenario |
| 245 |
family |
| 246 |
- semantic edge macros such as `\corascauses`, `\corasrelates`, |
| 247 |
`\corasconcerns`, `\corasassociates`, and `\corastreats` |
| 248 |
- table row macros: |
| 249 |
`\corashighlevelanalysisrow`, `\corashighlevelriskrow` |
| 250 |
- `\corasscope`, including `kind=asset-scope` and the stakeholder corner |
| 251 |
compartment options |
| 252 |
|
| 253 |
The `perspective` key applies to the public node macros and mounted-icon body |
| 254 |
nodes. `before` uses the base icon, `before-after` uses the outlined variant, |
| 255 |
and `after` uses the shaded variant. |
| 256 |
|
| 257 |
```latex |
| 258 |
\corasasset[ |
| 259 |
name=baseline, |
| 260 |
title={Asset}, |
| 261 |
perspective=before |
| 262 |
] |
| 263 |
\corasindirectasset[ |
| 264 |
name=transition, |
| 265 |
title={Indirect\\Asset}, |
| 266 |
perspective=before-after |
| 267 |
] |
| 268 |
\corastreatment[ |
| 269 |
name=target, |
| 270 |
title={Treatment}, |
| 271 |
perspective=after |
| 272 |
] |
| 273 |
``` |
| 274 |
|
| 275 |
Low-level primitives such as `\corasnode`, `\corasedge`, and `\corascontainer` |
| 276 |
remain available for compatibility, but they are documented as advanced |
| 277 |
interfaces rather than the preferred author-facing API. |
| 278 |
|
| 279 |
## Documentation |
| 280 |
|
| 281 |
The source for the package manual is |
| 282 |
[`docs/corasdiagram-doc.tex`](docs/corasdiagram-doc.tex). |
| 283 |
Compile it locally with: |
| 284 |
|
| 285 |
```bash |
| 286 |
(cd docs && TEXINPUTS=../tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error corasdiagram-doc.tex) |
| 287 |
``` |
| 288 |
|
| 289 |
The workflows publish the manual PDF and rendered example screenshots as CI |
| 290 |
artifacts, and the dedicated `Pages` workflow publishes the documentation site |
| 291 |
to GitHub Pages. |
| 292 |
|
| 293 |
## Release and Deployment |
| 294 |
|
| 295 |
The repository uses separate workflows for CI, Pages, and tagged releases: |
| 296 |
|
| 297 |
- `CI` validates changes on pull requests and branch pushes |
| 298 |
- `Pages` builds and deploys the documentation site from `main` |
| 299 |
- `Release` runs only for pushed `v*` tags and handles versioned release assets |
| 300 |
plus the gated CTAN publication step |
| 301 |
|
| 302 |
The `ctan-release` environment is the approval boundary for automated CTAN |
| 303 |
updates. The first CTAN submission is still expected to be done manually. For |
| 304 |
the exact release, approval, and versioning procedure, see |
| 305 |
[`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 306 |
|
| 307 |
## Regression Tests |
| 308 |
|
| 309 |
Run the semantic failure fixtures with: |
| 310 |
|
| 311 |
```bash |
| 312 |
python3 tools/check_negative_tests.py --engine pdflatex |
| 313 |
``` |
| 314 |
|
| 315 |
Run the visual regression suite with: |
| 316 |
|
| 317 |
```bash |
| 318 |
python3 tools/check_visual_regressions.py |
| 319 |
``` |
| 320 |
|
| 321 |
If a notation or layout change is intentional, regenerate the baselines in the |
| 322 |
same change with: |
| 323 |
|
| 324 |
```bash |
| 325 |
python3 tools/check_visual_regressions.py --update |
| 326 |
``` |
| 327 |
|
| 328 |
## Anchor Editor |
| 329 |
|
| 330 |
For interactive tuning of the symbol-table anchor maps, run: |
| 331 |
|
| 332 |
```bash |
| 333 |
python3 tools/coras_anchor_editor.py |
| 334 |
``` |
| 335 |
|
| 336 |
This starts a local browser-based editor that lets you drag the directional |
| 337 |
anchors for `asset`, `stakeholder`, the threat variants, and `vulnerability`, |
| 338 |
then save the values directly back into |
| 339 |
[`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty). |
| 340 |
|
| 341 |
The app also shows read-only previews for `scenario`, `treatment`, `incident`, |
| 342 |
and `risk`, using locally rebuilt images from the anchor regression fixture. |
| 343 |
|
| 344 |
## Contributing |
| 345 |
|
| 346 |
Contribution guidelines are in [`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 347 |
Please open issues for notation bugs, layout regressions, documentation gaps, |
| 348 |
or feature ideas. The public issue labels include `good first issue`, |
| 349 |
`help wanted`, `documentation`, `notation`, `layout`, and `ci`. |
| 350 |
|
| 351 |
## License |
| 352 |
|
| 353 |
This project is licensed under the MIT license. See [`LICENSE`](LICENSE). |
| 354 |
The vendored CORAS icon sources also carry upstream MIT attribution and |
| 355 |
provenance in [`NOTICE`](NOTICE). |