\documentclass[a4paper]{article}

\usepackage{lmodern}
\usepackage[margin=25mm]{geometry}
\usepackage[hidelinks]{hyperref}
\usepackage{array}
\usepackage{xcolor}
\usepackage{verbatim}
\usepackage{fvextra}
\usepackage{corasdiagram}

\title{\texttt{corasdiagram} Manual}
\date{Version \corasdiagramversion}
\newcommand{\keydefault}[1]{\underline{\texttt{#1}}}

\begin{document}

\maketitle
\tableofcontents

\section{Overview}

\texttt{corasdiagram} is a notation-first LaTeX package for the five core CORAS
diagram families:

\begin{itemize}
  \item asset diagrams
  \item threat diagrams
  \item risk diagrams
  \item treatment diagrams
  \item treatment overview diagrams
\end{itemize}

The package also provides high-level analysis risk tables with CORAS header
icons. The package ships with pre-rendered CORAS icons, semantic diagram
environments, concept-level node macros, and semantic edge macros. The current
supported engines are \texttt{pdflatex} and \texttt{lualatex}.

\section{Installation}

\subsection{Repository-Local Use}

Compile from the repository root with:

\begin{verbatim}
TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error \
  examples/corasdiagram-minimal.tex
\end{verbatim}

\subsection{User TEXMF Tree}

Copy \texttt{tex/latex/corasdiagram/} to
\texttt{\$HOME/texmf/tex/latex/corasdiagram/}. Refresh the TeX filename
database if your TeX distribution requires it.

\subsection{Release Bundle}

The release tooling assembles a CTAN-friendly bundle. Once the package is
published, installation can happen through the normal TeX package manager.

\section{Package Options}

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.22\linewidth}p{0.18\linewidth}p{0.46\linewidth}}
\hline
Option & Default & Meaning \\
\hline
iconset=color|bw & color & Select the color or black-and-white icon set for the base, outlined, and shaded icon variants. \\
icons-path=<path> & package icons & Override the icon directory path. \\
\hline
\end{tabular}
\end{center}

\section{Diagram Environments}

\begin{description}
  \item[\texttt{corasassetdiagram}] Stakeholders, assets, asset relations,
    and scope containers.
  \item[\texttt{corasthreatdiagram}] Threat sources, vulnerabilities, threat
    scenarios, unwanted incidents, and impacted assets.
  \item[\texttt{corasriskdiagram}] Threat sources, risks, and impacted assets.
  \item[\texttt{corastreatmentdiagram}] Treatment nodes together with the
    selected threat chain they mitigate.
  \item[\texttt{corastreatmentoverviewdiagram}] Treatments, risks, assets, and
    treatment fan-in via a junction.
\end{description}

Each environment enforces its legal CORAS vocabulary. Illegal node types or
edge relations raise package errors during compilation.

\section{High-Level Analysis Tables}

The package provides \texttt{corashighlevelanalysistable} and the alias
\texttt{corashighlevelrisktable} for the high-level analysis table style used
in CORAS reports. The environments are built on \texttt{longtable}, so they
can span multiple pages while repeating the icon header.

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.18\linewidth}p{0.27\linewidth}p{0.45\linewidth}}
\hline
Key & Values & Description \\
\hline
caption & empty or free text & Optional longtable caption shown above the first header. \\
label & empty or reference key & Optional \texttt{\textbackslash label} written together with the caption. \\
cause heading & \keydefault{Who/what causes it?} or free text & Header text for the left column. \\
event heading & \keydefault{How? What is the scenario or incident? What is harmed?} or free text & Header text for the middle column. \\
possibility heading & \keydefault{What makes it possible?} or free text & Header text for the right column. \\
cause width & \keydefault{24\% of \textbackslash textwidth} or dimension & Width of the left text column. \\
event width & \keydefault{40\% of \textbackslash textwidth} or dimension & Width of the middle text column. \\
possibility width & \keydefault{30\% of \textbackslash textwidth} or dimension & Width of the right text column. \\
column sep & \keydefault{10pt} or dimension & Horizontal spacing between columns. \\
row sep & \keydefault{0.8ex} or dimension & Extra vertical space inserted after each data row. \\
icon scale & \keydefault{1} or positive factor & Scales the header icon groups. Useful when the table is placed in a narrow minipage or column. \\
cause icons & default CORAS threat-source header content or raw TeX content & Override the icon content in the left header cell. \\
event icons & default CORAS scenario/incident/asset header content or raw TeX content & Override the icon content in the middle header cell. \\
possibility icons & default CORAS vulnerability header content or raw TeX content & Override the icon content in the right header cell. \\
\hline
\end{tabular}
\end{center}

Data rows are emitted with \texttt{\textbackslash corashighlevelanalysisrow} or
the alias \texttt{\textbackslash corashighlevelriskrow}. Both commands take
three mandatory arguments: cause, scenario/incident/harmed asset text, and
possibility text.

\begin{verbatim}
\begin{corashighlevelanalysistable}[
  caption={Documenting the high-level analysis}
]
  \corashighlevelanalysisrow
    {Hacker}
    {Breaks into system and compromises integrity\\
     or confidentiality of databases}
    {Use of web application and remote access;\\
     insufficient access control}
\end{corashighlevelanalysistable}
\end{verbatim}

\section{Public API}

\subsection{Canonical Node Macros}

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.34\linewidth}p{0.52\linewidth}}
\hline
Macro & Meaning \\
\hline
\textbackslash corashighlevelanalysisrow & One data row in a high-level analysis table. \\
\textbackslash corashighlevelriskrow & Alias for \textbackslash corashighlevelanalysisrow. \\
\textbackslash corasasset & Asset node with CORAS asset icon. \\
\textbackslash corasindirectasset & Indirect asset node with the dotted indirect-asset icon. \\
\textbackslash corasstakeholder & Stakeholder node with stakeholder icon. \\
\textbackslash corasthreataccidental & Accidental human threat source. \\
\textbackslash corasthreatdeliberate & Deliberate human threat source. \\
\textbackslash corasthreatnonhuman & Non-human threat source. \\
\textbackslash corasvulnerability & Vulnerability node. \\
\textbackslash corasscenario & Threat scenario node. \\
\textbackslash corasincident & Unwanted incident node. \\
\textbackslash corasunwantedincident & Alias for \textbackslash corasincident. \\
\textbackslash corasrisk & Risk node with title and level metadata. \\
\textbackslash corastreatment & Treatment node. \\
\textbackslash corasjunction & Junction node for treatment overview fan-in. \\
\hline
\end{tabular}
\end{center}

\paragraph{Indirect Assets}

\texttt{\textbackslash corasindirectasset} is semantically an asset node with a
distinct dotted indirect-asset symbol. It can therefore be used anywhere the
package expects an asset concept, including asset-diagram auto-layout lanes,
asset-scope grouping, and the normal asset relation macros.

\paragraph{Change-Modeling Perspectives}

The \texttt{perspective} key is the public change-modeling switch used across
icon-backed nodes and mounted-icon body nodes:
\texttt{before} keeps the base icon,
\texttt{before-after} selects the outlined transition variant, and
\texttt{after} selects the shaded result variant.

This applies to icon-backed nodes such as
\texttt{\textbackslash corasasset},
\texttt{\textbackslash corasindirectasset},
\texttt{\textbackslash corasstakeholder},
the threat-source macros, and
\texttt{\textbackslash corasvulnerability};
to mounted-icon body nodes such as
\texttt{\textbackslash corasscenario},
\texttt{\textbackslash corasunwantedincident},
\texttt{\textbackslash corasrisk}, and
\texttt{\textbackslash corastreatment};
and to
\texttt{\textbackslash corasriskref}.

Underlined values in the key tables below are the defaults used by the package.

\paragraph{Worked Perspective Example}

\begin{center}
\begin{corasassetdiagram}[x=.85cm,y=.85cm,layout=manual]
  \corasasset[
    at={(0,0)},
    title={Asset},
    perspective=before
  ]
  \corasindirectasset[
    at={(3.2,0)},
    title={Indirect\\Asset},
    perspective=before-after
  ]
  \corasstakeholder[
    at={(6.4,0)},
    title={Stakeholder},
    perspective=after
  ]
\end{corasassetdiagram}
\end{center}

\begin{center}
\begin{corastreatmentdiagram}[x=.85cm,y=.85cm,layout=manual]
  \corasscenario[
    at={(0,0)},
    title={Scenario},
    meta={1 per year},
    perspective=before
  ]
  \corasunwantedincident[
    at={(4.5,0)},
    title={Incident},
    perspective=before-after
  ]
  \corastreatment[
    at={(8.6,0)},
    title={Treatment},
    perspective=after
  ]
\end{corastreatmentdiagram}
\end{center}

\noindent
The first row shows the three perspective states on icon-backed nodes. The
second row shows the same key on mounted-icon body nodes, where only the icon
changes and the underlying ellipse or rectangle geometry stays the same.

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.18\linewidth}p{0.27\linewidth}p{0.45\linewidth}}
\hline
Key & Values & Description \\
\hline
name & auto-generated identifier & Public node name used by later edges, scopes, and references. \\
title & free text & Primary label text rendered in the node. \\
meta & empty or free text & Secondary metadata line below the title. \\
level & empty or free text & Secondary level line, mainly used by risk nodes. \\
perspective & \keydefault{before} | \texttt{before-after} | \texttt{after} & Selects the CORAS change-modeling perspective: base icon, outlined icon, or shaded icon. \\
scope & empty or scope name & Adds the node to a named scope fit group. \\
at & empty or TikZ coordinate & Explicit placement; wins over automatic placement. \\
order & empty or positive integer & Sets the lane order used by auto layout. \\
text width & empty or dimension & Overrides the node type's built-in text wrapping width. \\
layout & \keydefault{auto} | \texttt{manual} & Overrides the diagram's placement mode for a node. \\
min edge gap & empty or dimension & Node-level override for the minimum border-to-border spacing enforced by auto layout and relative placement helpers. \\
right of & empty or node name & Relative placement to the right of another node. \\
below of & empty or node name & Relative placement below another node. \\
incident of & empty or node name & Relative placement to the right of an incident node. \\
treats & empty or node name & Relative placement above the treated node. \\
harms & empty or node name & Relative placement to the left of the harmed node. \\
horizontal gap & \keydefault{12mm} or dimension & Horizontal offset used by relative placement helpers. \\
vertical gap & \keydefault{14mm} or dimension & Vertical offset used by relative placement helpers. \\
tikz & empty or raw TikZ options & Advanced style override passed to the underlying node. \\
\hline
\end{tabular}
\end{center}

\subsection{Semantic Edge Macros}

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.28\linewidth}p{0.58\linewidth}}
\hline
Macro & Meaning \\
\hline
\textbackslash corascauses & Solid causal edge with open line arrowhead. \\
\textbackslash corasrelates & Solid relation/impact edge with open line arrowhead. \\
\textbackslash corasconcerns & Dashed concern edge, typically stakeholder to asset. \\
\textbackslash corasassociates & Dashed non-causal association edge. \\
\textbackslash corastreats & Dashed curved treatment edge leaving the source orthogonally. \\
\hline
\end{tabular}
\end{center}

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.18\linewidth}p{0.27\linewidth}p{0.45\linewidth}}
\hline
Key & Values & Description \\
\hline
from & node name & Start node for the edge. \\
to & node name & End node for the edge. \\
label & empty or free text & Optional label placed on the edge. \\
pos & \keydefault{.5} or number & Relative position for the edge label or risk reference anchor. \\
route & \keydefault{auto} | \texttt{straight} | \texttt{hv} | \texttt{vh} & Selects the default routing strategy for non-treatment edges. \\
path & empty or raw TikZ path operator & Advanced override for the edge path, such as \texttt{-|}. \\
tikz & empty or raw TikZ draw options & Advanced style override passed to the underlying draw command. \\
label options & \keydefault{fill=white,inner sep=1pt} or raw TikZ options & Advanced style override for the edge label node. \\
\hline
\end{tabular}
\end{center}

The higher-level semantic edge macros choose the underlying edge type and
semantic relation automatically, so the low-level \texttt{type} and
\texttt{semantic} keys are normally only needed with
\texttt{\textbackslash corasedge}.

\subsection{Scopes and Containers}

\texttt{\textbackslash corasscope} is the public scope/container helper. The
important keys are:

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.18\linewidth}p{0.27\linewidth}p{0.45\linewidth}}
\hline
Key & Values & Description \\
\hline
name & auto-generated identifier & Public scope/container node name. \\
title & empty or free text & Optional title shown on the scope. \\
scope & empty or scope name & Reuses all nodes previously tagged with the same scope name. \\
fit & empty or TikZ fit list & Explicit fit list such as \texttt{(a) (b) (c)}. \\
kind & \keydefault{system} | \texttt{asset-scope} | \texttt{analysis} | \texttt{risk-group} | \texttt{treatment-scope} & Selects the container styling. \\
padding & \keydefault{5mm} or dimension & General scope padding; \texttt{asset-scope} falls back to \keydefault{1.0mm}. \\
stakeholder & empty or node name & Selects the stakeholder node used for the asset-scope corner compartment. \\
stakeholder corner & \keydefault{left} | \texttt{right} & Chooses which top corner gets the stakeholder compartment. \\
stakeholder xsep & empty or dimension & Horizontal padding inside the asset-scope stakeholder square; defaults to \keydefault{0.25mm}. \\
stakeholder ysep & empty or dimension & Vertical padding inside the asset-scope stakeholder square; defaults to \keydefault{0.25mm}. \\
tikz & empty or raw TikZ options & Advanced style override for the container node. \\
title tikz & empty or raw TikZ options & Advanced style override for the scope title node. \\
\hline
\end{tabular}
\end{center}

The \texttt{asset-scope} kind renders the rounded asset-diagram container with
the stakeholder corner compartment. The official threat, risk, treatment, and
treatment overview examples do not use containers.

\subsection{Advanced Compatibility API}

The package still ships the lower-level primitives
\texttt{\textbackslash corasnode}, \texttt{\textbackslash corasedge}, and
\texttt{\textbackslash corascontainer}. They remain available for advanced
usage and backward compatibility, but the semantic wrappers are the preferred
public API.

\section{Layout Behavior}

The package supports both explicit coordinates and role-aware automatic
placement. Manual placement always wins when \texttt{at=<...>} is given.
The \texttt{min edge gap} key acts as a lower bound on visible
border-to-border spacing for both auto placement and the relative helper keys.
Explicit \texttt{horizontal gap} and \texttt{vertical gap} values still matter,
but they can only increase that spacing.

Important layout-related keys:

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.18\linewidth}p{0.27\linewidth}p{0.45\linewidth}}
\hline
Key & Values & Description \\
\hline
layout & \keydefault{auto} | \texttt{manual} & Switch between role-aware automatic placement and fully explicit placement. \\
at & empty or TikZ coordinate & Place a node directly at a coordinate; takes precedence over all other layout keys. \\
order & empty or positive integer & Controls row ordering inside the role lane used by auto layout. \\
min edge gap & \keydefault{8mm} or dimension & Minimum border-to-border spacing preserved for auto placement and relative helpers; ignored when \texttt{at=<...>} is given. \\
scope & empty or scope name & Groups asset-diagram nodes into a fit-based container. \\
right of & empty or node name & Places a node to the right of another node using \texttt{horizontal gap}. \\
below of & empty or node name & Places a node below another node using \texttt{vertical gap}. \\
incident of & empty or node name & Places a node to the right of an incident node. \\
treats & empty or node name & Places a node above the treated node. \\
harms & empty or node name & Places a node to the left of the harmed node. \\
\hline
\end{tabular}
\end{center}

\section{Complete Examples}

\subsection{Asset Diagram}

This example uses \texttt{\textbackslash corasindirectasset} for the dependent
asset. Semantically it is still an asset node, but it renders with the dotted
indirect-asset symbol.

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

\subsection{Threat Diagram}

\begin{center}
\begin{corasthreatdiagram}[x=.75cm,y=.75cm]
  \corasthreataccidental[name=doc-employee,order=1,title={Employee}]
  \corasscenario[
    name=doc-remote,
    order=1,
    title={Remote access},
    meta={1 per 6 months}
  ]
  \corasvulnerability[
    name=doc-oldweb,
    order=1,
    title={Old\\webserver}
  ]
  \corasunwantedincident[
    name=doc-disclosure,
    order=1,
    title={Disclosure\\of data}
  ]
  \corasasset[
    name=doc-privacy,
    order=1,
    title={Data\\privacy}
  ]
  \corascauses[from=doc-employee,to=doc-oldweb]
  \corascauses[from=doc-oldweb,to=doc-remote]
  \corascauses[from=doc-remote,to=doc-disclosure]
  \corasrelates[from=doc-disclosure,to=doc-privacy]
\end{corasthreatdiagram}
\end{center}

\subsection{Risk Diagram}

\begin{center}
\begin{corasriskdiagram}[x=.8cm,y=.8cm]
  \corasthreatnonhuman[
    name=doc-infra,
    order=1,
    title={IT-infrastructure}
  ]
  \corasrisk[
    name=doc-risk,
    order=1,
    title={Application\\outage},
    meta={1 per year},
    level=medium
  ]
  \corasasset[
    name=doc-availability,
    order=1,
    title={Application\\availability}
  ]
  \corascauses[from=doc-infra,to=doc-risk]
  \corasrelates[from=doc-risk,to=doc-availability]
\end{corasriskdiagram}
\end{center}

\subsection{Treatment Diagram}

\begin{center}
\begin{corastreatmentdiagram}[x=.75cm,y=.75cm]
  \corasthreataccidental[name=doc-user,order=1,title={Employee}]
  \corasvulnerability[
    name=doc-vulnerability,
    order=1,
    title={Old\\webserver}
  ]
  \corasscenario[
    name=doc-threat,
    order=1,
    title={Remote access},
    meta={1 per 6 months}
  ]
  \corasunwantedincident[
    name=doc-incident,
    order=1,
    title={Disclosure\\of data},
    meta={1 per year}
  ]
  \corasasset[
    name=doc-asset2,
    order=1,
    title={Data\\privacy}
  ]
  \corastreatment[
    name=doc-training,
    order=1,
    title={Security\\training}
  ]
  \corascauses[from=doc-user,to=doc-vulnerability]
  \corascauses[from=doc-vulnerability,to=doc-threat]
  \corascauses[from=doc-threat,to=doc-incident]
  \corasrelates[from=doc-incident,to=doc-asset2]
  \corastreats[from=doc-training,to=doc-threat]
\end{corastreatmentdiagram}
\end{center}

\subsection{Treatment Overview Diagram}

\begin{center}
\begin{corastreatmentoverviewdiagram}[x=.75cm,y=.75cm]
  \corasrisk[
    name=doc-risk1,
    order=1,
    title={Disclosure\\of data},
    meta={direct asset},
    level=unacceptable
  ]
  \corasasset[
    name=doc-asset3,
    order=1,
    title={Data\\privacy}
  ]
  \corasjunction[name=doc-junction]
  \corastreatment[
    name=doc-treatment1,
    order=1,
    title={Limit access}
  ]
  \corastreatment[
    name=doc-treatment2,
    order=2,
    title={Upgrade\\server}
  ]
  \corasrelates[from=doc-risk1,to=doc-asset3]
  \corastreats[from=doc-treatment1,to=doc-junction]
  \corastreats[from=doc-treatment2,to=doc-junction]
  \corastreats[from=doc-junction,to=doc-risk1]
\end{corastreatmentoverviewdiagram}
\end{center}

\subsection{High-Level Analysis Table}

\begingroup
\small
\begin{corashighlevelanalysistable}[
  caption={Documenting the high-level analysis}
]
  \corashighlevelanalysisrow
    {Hacker}
    {Breaks into system and compromises integrity or confidentiality of databases}
    {Use of web application and remote access; insufficient access control}

  \corashighlevelanalysisrow
    {Employee}
    {Sloppiness compromises integrity or confidentiality of databases}
    {Lack of competence; work processes not aligned with policy}

  \corashighlevelanalysisrow
    {System failure}
    {Online store goes down because of failure of web application or loss of network connection}
    {Immature technology; loss of network connection}

  \corashighlevelanalysisrow
    {Employee}
    {Collection and processing of personal data diverge from data protection laws}
    {Lack of competence on data protection laws; insufficient routines for processing personal data}
\end{corashighlevelanalysistable}
\endgroup

\section{Source Files}

The repository ships these main author-facing files:

\begin{itemize}
  \item \texttt{tex/latex/corasdiagram/corasdiagram.sty}
  \item \texttt{examples/corasdiagram-minimal.tex}
  \item \texttt{examples/corasdiagram-demo.tex}
  \item \texttt{tests/corasdiagram/*.tex}
\end{itemize}

\section{Build and Release Tooling}

The project includes helper scripts for:

\begin{itemize}
  \item building icon PDFs from the original SVG files
  \item running semantic failure tests
  \item assembling a CTAN-friendly release bundle
  \item building a static documentation site with rendered screenshots
\end{itemize}

See \texttt{CONTRIBUTING.md} for the current repository-root commands.

\section{License}
\IfFileExists{LICENSE}{%
  \verbatiminput{LICENSE}%
}{%
  \verbatiminput{../LICENSE}%
}

\section{Notice}
\IfFileExists{NOTICE}{%
  \VerbatimInput[
    breaklines=true,
    breakanywhere=true
  ]{NOTICE}%
}{%
  \VerbatimInput[
    breaklines=true,
    breakanywhere=true
  ]{../NOTICE}%
}

\end{document}