corasdiagram

corasdiagram is a LaTeX package for authoring CORAS diagrams with reusable notation macros, package-managed icons, semantic diagram environments, and high-level analysis tables.

The package currently supports the five basic CORAS diagram families:

• asset diagrams
• threat diagrams
• risk diagrams
• treatment diagrams
• treatment overview diagrams

It also supports high-level analysis risk tables with CORAS header icons.

For narrow layouts such as a side-by-side minipage in Overleaf, the high-level analysis table accepts icon scale=<factor> to shrink the header icon groups, for example icon scale=0.6.

The supported TeX engines are pdflatex and lualatex.

Author and Contact

• Author and maintainer: Fabian Robert Smith
• Contact email: <fabian.smith@me.com>
• Repository and issue tracker: github.com/smithfabian/corasdiagram (issues)

How the Project Works

This repository keeps the package source, documentation, regression tests, and release tooling in one place.

Canonical sources of truth:

• VERSION is the canonical repository release number.
• tex/latex/corasdiagram/corasdiagram-version.tex is the TeX runtime mirror of that version and must match VERSION.
• the \ProvidesPackage date in tex/latex/corasdiagram/corasdiagram.sty must match the current release date in CHANGELOG.md
• assets/icons-src/ holds the canonical icon sources.
• NOTICE records provenance and the upstream MIT notice for the vendored icon sources.
• tex/latex/corasdiagram/icons/ holds the generated runtime icon assets used by the package.
• tests/corasdiagram/snapshots/ holds the committed visual regression baselines.
• ctan/metadata.json holds the committed CTAN metadata used by the release tooling.

Workflow map:

• normal development happens on branches and pull requests
• merges to main trigger CI and deploy the documentation site through the dedicated Pages workflow
• pushed version tags matching vX.Y.Z trigger the Release workflow
• the release workflow verifies that the tag matches VERSION and that the package header date matches the current CHANGELOG.md release date, builds the release archive, publishes the GitHub release assets, and waits at the ctan-release environment before any CTAN upload can continue

For the full contributor runbook, change checklists, and release procedure, see CONTRIBUTING.md.

Repository Layout

The package source lives in tex/latex/corasdiagram/, examples live in examples/, the manual source lives in docs/, semantic regression tests live in tests/corasdiagram/, and committed visual baselines live in tests/corasdiagram/snapshots/. CTAN metadata lives in ctan/, and the helper scripts used by CI, Pages, releases, and local development live in tools/.

Installation

For local development inside this repository, compile with:

TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex

For a user-level TEXMF installation from a repository checkout, copy tex/latex/corasdiagram/ to ~/texmf/tex/latex/corasdiagram/ and refresh the TeX filename database if your distribution requires it.

The release workflow also assembles a CTAN-friendly distribution bundle with runtime files flattened under tex/, documentation under doc/, and the top-level metadata files such as LICENSE and NOTICE. If you are installing from that bundle manually, copy the contents of tex/ into ~/texmf/tex/latex/corasdiagram/. Once the package is published to CTAN or TeX Live, installation can happen through the normal package manager for the TeX distribution.

Using In Your Own Project

The package can be used directly in both Overleaf projects and ordinary local LaTeX projects by copying the package file together with its icon assets.

Overleaf

Upload these from the repository:

• tex/latex/corasdiagram/corasdiagram.sty
• the full tex/latex/corasdiagram/icons/ directory

The simplest Overleaf layout is:

main.tex
corasdiagram.sty
icons/
  corasdiagram-asset.pdf
  corasdiagram-stakeholder.pdf
  corasdiagram-risk.pdf
  ...

Then load the package normally:

\usepackage{corasdiagram}

This works because the package resolves the default icon path relative to the location of corasdiagram.sty.

If you prefer to keep the package in a subfolder, keep the icons/ directory beside the .sty file, for example:

main.tex
corasdiagram/
  corasdiagram.sty
  icons/
    corasdiagram-asset.pdf
    corasdiagram-stakeholder.pdf
    ...

and load it with:

\usepackage{corasdiagram/corasdiagram}

If your icon directory is somewhere else, set it explicitly:

\usepackage[icons-path=coras-assets/icons]{corasdiagram}

Local LaTeX Projects

For a normal local project outside this repository, copy the same files into your project tree:

my-project/
  main.tex
  corasdiagram.sty
  icons/

and load the package with:

\usepackage{corasdiagram}

You can also keep the package in a subdirectory and point LaTeX at it in the usual way, either by using a TEXMF tree or by loading the package through its relative path:

\usepackage{vendor/corasdiagram/corasdiagram}

In that case, keep the icons/ folder next to the .sty file or pass an explicit icons-path=....

Minimal Example

\documentclass{article}
\usepackage{corasdiagram}

\begin{document}

\begin{corasassetdiagram}[x=1cm,y=1cm]
  \corasstakeholder[
    name=stakeholder,
    scope=asset-scope,
    order=1,
    title={Stakeholder}
  ]
  \corasasset[
    name=asset,
    scope=asset-scope,
    order=1,
    title={Asset}
  ]
  \corasindirectasset[
    name=indirect,
    scope=asset-scope,
    order=2,
    title={Indirect\\Asset}
  ]
  \corasscope[
    name=asset-box,
    scope=asset-scope,
    kind=asset-scope,
    stakeholder=stakeholder,
    stakeholder corner=left
  ]
  \corasrelates[from=asset,to=indirect]
\end{corasassetdiagram}

\end{document}

Screenshots

The release workflow publishes the manual PDF and rendered diagram screenshots to GitHub Pages and the release artifacts. The committed source tree keeps only the package sources and example .tex files.

Public API

The current supported semantic package API is:

• package options: iconset, icons-path
• common node keys such as perspective=before|before-after|after
• diagram environments: corasassetdiagram, corasthreatdiagram, corasriskdiagram, corastreatmentdiagram, corastreatmentoverviewdiagram
• high-level analysis table environments: corashighlevelanalysistable, corashighlevelrisktable
• concept node macros such as \corasasset, \corasindirectasset, \corasstakeholder, \corasrisk, \corastreatment, and the threat/vulnerability/scenario family
• semantic edge macros such as \corascauses, \corasrelates, \corasconcerns, \corasassociates, and \corastreats
• table row macros: \corashighlevelanalysisrow, \corashighlevelriskrow
• \corasscope, including kind=asset-scope and the stakeholder corner compartment options

The perspective key applies to the public node macros and mounted-icon body nodes. before uses the base icon, before-after uses the outlined variant, and after uses the shaded variant.

\corasasset[
  name=baseline,
  title={Asset},
  perspective=before
]
\corasindirectasset[
  name=transition,
  title={Indirect\\Asset},
  perspective=before-after
]
\corastreatment[
  name=target,
  title={Treatment},
  perspective=after
]

Low-level primitives such as \corasnode, \corasedge, and \corascontainer remain available for compatibility, but they are documented as advanced interfaces rather than the preferred author-facing API.

Documentation

The source for the package manual is docs/corasdiagram-doc.tex. Compile it locally with:

(cd docs && TEXINPUTS=../tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error corasdiagram-doc.tex)

The workflows publish the manual PDF and rendered example screenshots as CI artifacts, and the dedicated Pages workflow publishes the documentation site to GitHub Pages.

Release and Deployment

The repository uses separate workflows for CI, Pages, and tagged releases:

• CI validates changes on pull requests and branch pushes
• Pages builds and deploys the documentation site from main
• Release runs only for pushed v* tags and handles versioned release assets plus the gated CTAN publication step

The ctan-release environment is the approval boundary for automated CTAN updates. The first CTAN submission is still expected to be done manually. For the exact release, approval, and versioning procedure, see CONTRIBUTING.md.

Regression Tests

Run the semantic failure fixtures with:

python3 tools/check_negative_tests.py --engine pdflatex

Run the visual regression suite with:

python3 tools/check_visual_regressions.py

If a notation or layout change is intentional, regenerate the baselines in the same change with:

python3 tools/check_visual_regressions.py --update

Anchor Editor

For interactive tuning of the symbol-table anchor maps, run:

python3 tools/coras_anchor_editor.py

This starts a local browser-based editor that lets you drag the directional anchors for asset, stakeholder, the threat variants, and vulnerability, then save the values directly back into tex/latex/corasdiagram/corasdiagram.sty.

The app also shows read-only previews for scenario, treatment, incident, and risk, using locally rebuilt images from the anchor regression fixture.

Contributing

Contribution guidelines are in CONTRIBUTING.md. Please open issues for notation bugs, layout regressions, documentation gaps, or feature ideas. The public issue labels include good first issue, help wanted, documentation, notation, layout, and ci.

License

This project is licensed under the MIT license. See LICENSE. The vendored CORAS icon sources also carry upstream MIT attribution and provenance in NOTICE.