AppArmor Language Server (apparmor-language-server)

A full-featured Language Server Protocol server for editing AppArmor profiles, written in Python using pygls.

Features

Contributing and Issues

We welcome contributions! Please feel free to open a Merge Request.

If you find a bug or have a feature request, please check the Issue tracker to see if it has already been reported. If not, feel free to open a new issue.

Installation

From snap

sudo snap install apparmor-language-server

The snap provides the apparmor-language-server, apparmor-lint, and apparmor-format commands. Access to /etc/apparmor.d for resolving include directives and indexing system profiles is granted automatically.

For audit-log rule suggestions the snap needs the log-observe interface (to run journalctl and read AppArmor denials from the system journal):

sudo snap connect apparmor-language-server:log-observe

For accurate filesystem path completions, connect the system-backup interface:

sudo snap connect apparmor-language-server:system-backup

The snap reads the host's /etc/apparmor.d (and /etc/apparmor) only. A profile that includes a file by absolute path elsewhere, such as snapd's usr.lib.snapd.snap-confine.real with its #include "/var/lib/snapd/apparmor/snap-confine", cannot be fully checked from the snap: the include is reported as unreadable. Install from PyPI to check such profiles.

From PyPI

pip install apparmor-language-server

From source

git clone https://gitlab.com/apparmor/apparmor-language-server
cd apparmor-language-server
pip install .

Or install dependencies directly without building a package:

pip install pygls lsprotocol
python -m apparmor_language_server          # stdio mode
python -m apparmor_language_server --port 2087  # TCP mode on 127.0.0.1:2087

Running the server

stdio (default — used by most editors)

apparmor-language-server
# or
python -m apparmor_language_server

TCP (useful for debugging)

apparmor-language-server --port 2087

Standalone linter (apparmor-lint)

The package also ships a apparmor-lint command-line tool that runs the same parser and diagnostic checks as the language server — useful in CI, pre-commit hooks, or when you just want a quick check from the shell without firing up an editor.

# Lint one or more files
apparmor-lint /etc/apparmor.d/usr.bin.foo
apparmor-lint profile another-profile

# Read from stdin
cat profile | apparmor-lint -

# Skip the external apparmor_parser cross-check
apparmor-lint --no-parser profile

# Machine-readable output for CI
apparmor-lint --format json profile

Output format

The default pretty format is GCC-compatible so editors and tools that already parse cc(1) output (Vim quickfix, Emacs compile, grep -nH, …) work out of the box:

profile:3:3: error: Unknown capability 'bad_cap_xyz'. … [unknown-capability] (apparmor-language-server)
profile:5:3: error: Network rule: netlink may only specify type 'dgram' or 'raw' (got 'stream'). [netlink-type-restricted] (apparmor-language-server)

--format json emits an array of records, each with path, uri, severity, message, code, source, line, column, end_line, and end_column — handy for piping into jq or aggregating across files.

Options

Exit codes

Library API

apparmor_language_server.lint also exposes the linter as a Python API for embedding in other tools:

from apparmor_language_server.lint import lint_file, lint_text

# Returns dict[str, list[lsprotocol.types.Diagnostic]] keyed by URI.
diags = lint_file(Path("profile"), run_apparmor_parser=False)
diags = lint_text("profile x { /foo r, }\n")

Standalone formatter (apparmor-format)

The package also ships an apparmor-format command-line formatter that uses the same formatter and renderer behavior as the language server.

# Print formatted output to stdout
apparmor-format profile

# Rewrite a file in place
apparmor-format --in-place profile

# Check whether files would change
apparmor-format --check profile another-profile

# Show a unified diff of what would change (useful in CI and pre-commit hooks)
apparmor-format --diff profile another-profile

# Read from stdin
cat profile | apparmor-format -

Modes

Formatter options

These flags cover the formatter-specific behaviour; include resolution uses the parser defaults and missing includes do not prevent formatting.

Exit codes

Server configuration

Environment variables

LSP workspace settings

These are passed to the server via the standard LSP workspace/didChangeConfiguration notification, nested under the apparmor key. How you set them depends on your editor (see the examples below each editor section).

Editor configuration

Neovim (with nvim-lspconfig)

-- In your init.lua or a plugin file
local lspconfig = require('lspconfig')
local configs   = require('lspconfig.configs')

-- Register the server if it is not already known
if not configs.apparmor_language_server then
  configs.apparmor_language_server = {
    default_config = {
      cmd         = { 'apparmor-language-server' },  -- or { 'python', '-m', 'apparmor_language_server' }
      filetypes   = { 'apparmor' },
      root_dir    = lspconfig.util.root_pattern('.git', '/etc/apparmor.d'),
      single_file_support = true,
      settings    = {},
    },
  }
end

lspconfig.apparmor_language_server.setup({
  on_attach = function(client, bufnr)
    -- Enable format-on-save
    vim.api.nvim_create_autocmd('BufWritePre', {
      buffer = bufnr,
      callback = function()
        vim.lsp.buf.format({ async = false })
      end,
    })
  end,
})

-- Tell Neovim about the AppArmor filetype
vim.filetype.add({
  pattern = {
    ['/etc/apparmor.d/.*']     = 'apparmor',
    ['/etc/apparmor/.*%.conf'] = 'apparmor',
    ['.*%.apparmor']           = 'apparmor',
  },
})

VS Code

The extension is published on the VS Code Marketplace (publisher AlexMurray) — this is built from the upstream project at gitlab.com/apparmor/apparmor-language-server/editors/vscode. Search for AppArmor Language Server in the Extensions view or install from the command line:

code --install-extension AlexMurray.apparmor-language-server

Alternatively, a VS Code extension is included in editors/vscode/. To build and install it locally:

cd editors/vscode
npm install
npm run compile
npx vsce package --no-dependencies   # produces apparmor-language-server-*.vsix
code --install-extension apparmor-language-server-*.vsix

The extension locates the server automatically in this order:

1. apparmor.serverPath setting — explicit path to the apparmor-language-server executable.
2. apparmor-language-server on PATH — covers system installs, pip install --user, and activated virtualenvs.
3. The active Python interpreter from the Python extension, if installed.
4. apparmor.pythonPath setting, or python3 as a last resort.

Files matching **/apparmor.d/** are recognised automatically. Use the AppArmor: Restart Language Server command palette entry to restart the server after installing or upgrading the Python package.

Emacs (with eglot)

(add-to-list 'auto-mode-alist '("/etc/apparmor\\.d/.*" . apparmor-mode))
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(apparmor-mode . ("apparmor-language-server"))))

Emacs (with lsp-mode)

(with-eval-after-load 'lsp-mode
  (lsp-register-client
   (make-lsp-client
    :new-connection (lsp-stdio-connection '("apparmor-language-server"))
    :major-modes '(apparmor-mode)
    :server-id 'apparmor-language-server)))

Helix

In ~/.config/helix/languages.toml:

[[language]]
name              = "apparmor"
scope             = "source.apparmor"
file-types        = ["apparmor", { glob = "/etc/apparmor.d/**" }]
language-servers  = ["apparmor-language-server"]
comment-token     = "#"
indent            = { tab-width = 2, unit = "  " }

[language-server.apparmor-language-server]
command = "apparmor-language-server"

Sublime Text (with LSP package)

In LSP.sublime-settings:

{
  "clients": {
    "apparmor-language-server": {
      "enabled": true,
      "command": ["apparmor-language-server"],
      "selector": "source.apparmor"
    }
  }
}

Formatting options

The formatter respects the editor's tabSize setting (passed via the LSP DocumentFormattingParams). All other options are controlled via the apparmor.formatting.* server configuration keys described in the server configuration table above; the apparmor-format CLI exposes the same options as command-line flags.

Diagnostics reference

file-rule-subsumed and rule-subsumed — examples

profile example /usr/bin/example {
    /usr/bin/foo r,       # flagged: subsumed by the rule below
    /usr/bin/*   r,

    capability net_bind_service,          # flagged: subsumed by the rule below
    capability net_bind_service net_admin,
}

Known limitations

Rules that appear inside qualifier blocks (owner { }, audit { }, deny { }, …) or inside if defined conditional blocks are excluded from the comparison. Rules contributed by transitively included abstractions are checked — the diagnostic message names the top-level include directive that introduced the broader rule. Rules inside ProfileNode bodies found in included files (sub-profiles) are not compared, as those represent separate confinement domains. This applies to both file-rule-subsumed and rule-subsumed.

For file-rule-subsumed: @{VAR} references are resolved against the variable definitions in scope (including the profile-local @{profile_name} and @{attach_path}), so /etc/foo r, is detected as subsumed by @{etc_ro}/foo r, from an included abstraction. Detection stays conservative: a rule is only flagged when every expansion of its path is provably covered (a multi-valued variable that is only partially covered never triggers), and undefined variables are compared as opaque tokens. When both rules have partial globs in the same path-component position (e.g. foo* vs foo?), subsumption cannot be determined structurally and is conservatively skipped.

Suppressing diagnostics

Place a # apparmor-lint: ignore=<code> comment at the end of a line where a rule is defined, or on the line immediately before a rule, to silence one or more diagnostics for that rule only. Multiple codes can be listed comma-separated. A blank line between the comment and the rule cancels the annotation. The space after # is optional.

profile example /usr/bin/example {
  # This rule intentionally uses unconfined exec — required for the wrapper.
  /usr/bin/helper ux, # apparmor-lint: ignore=dangerous-exec

  # Suppress multiple codes on one rule (ux on a path containing an
  # undefined variable).
  # apparmor-lint: ignore=dangerous-exec,undefined-variable
  @{helper_path} ux,

  # The annotation below is cleared by the blank line and has no effect.
  # apparmor-lint: ignore=unknown-capability

  capability not_a_real_cap,
}

Annotations at the top of a file

The preamble is the uninterrupted block of comment lines at the very start of a file — it ends at the first blank line or the first non-comment statement, whichever comes first. Preamble comments are never attached to any node, which protects copyright notices, SPDX identifiers, and other licence headers from being accidentally deleted by code actions.

Document-wide suppression: A # apparmor-lint: ignore= annotation placed in the preamble silences that diagnostic code for the entire file. This is the recommended way to suppress diagnostics such as missing-abi-declaration and missing-tunables-global that are not attached to a specific statement:

# Copyright (C) 2024 Example Corp
# SPDX-License-Identifier: GPL-2.0
# apparmor-lint: ignore=missing-abi-declaration,missing-tunables-global
include <my-custom-tunables>
profile p { ... }

Multiple codes may be listed on one line (comma-separated) or spread across several # apparmor-lint: ignore= lines in the preamble block — all are applied. Note that parse-error and apparmor-parser-error cannot be suppressed this way.

Important: the preamble ends as soon as a non-comment statement appears. If the first line of the file is a non-comment (e.g. abi <abi/4.0>,), any annotation on the next line is already outside the preamble and will be treated as a node-level annotation on the following statement — not as a document-wide suppression. To use document-wide suppression alongside an abi declaration, place the annotation before the abi line:

# apparmor-lint: ignore=missing-tunables-global
abi <abi/4.0>,
include <my-custom-tunables>
profile p { ... }

Node-level annotation after a copyright block: To apply a # apparmor-lint: ignore= annotation to only the first statement in the file (rather than the whole document), place a blank line between the preamble and the annotation so it falls outside the preamble zone:

# Copyright (C) 2024 Example Corp
# SPDX-License-Identifier: GPL-2.0

# apparmor-lint: ignore=missing-tunables-global
include <my-custom-tunables>

Code actions reference

Quick fixes are offered automatically when a diagnostic appears on a line. Editors typically show them via a lightbulb or a <leader>ca / Ctrl+. keybinding.

⭐ Marked as the preferred action (used by editor auto-fix commands).

Audit-log rule suggestions

Beyond the diagnostic quick fixes above, the server offers source-kind code actions derived from the system audit log — the same workflow aa-logprof provides interactively, but inside the editor. With the cursor anywhere in a profile, request source actions (in VS Code: right-click → Source Action…; in Neovim: vim.lsp.buf.code_action({ context = { only = { "source" } } })).

When audit events recorded for a profile map to rules it does not already grant, the server publishes an information-level diagnostic on the profile header (code audit-log-denials, e.g. "3 rule suggestions available from 7 audit events recorded for this profile — review via source code actions"), so available suggestions surface in the editor's Problems panel without any action on your part. Suppress it for a profile with a # apparmor-lint: ignore=audit-log-denials annotation, or disable the feature entirely with apparmor.auditLog.enable. The diagnostic is editor-only: apparmor-lint output never depends on the machine's audit log.

For every DENIED (enforce mode) or ALLOWED (complain mode) audit event recorded for the profile being edited, the server suggests the rule that would permit it:

• an add all exact rules action listed first, then one action per suggested rule, with rules inserted before a trailing include if exists <local/…> (or the closing brace);
• each file rule is followed by aa-logprof-style widened variants — the extension-preserving glob (dir/*.ext), the directory glob (dir/*) and, for deep paths, one level up (parent/**) — so a denial on a single locale file can be resolved with one click as …/locales/** r, instead; exec rules are never widened;
• action titles show how many audit events each rule would resolve and the rule's 0–10 risk rank from severity.db (the database aa-logprof uses);
• suggestions already granted by the profile or its included abstractions are filtered out using the same subsumption logic as the rule-subsumed diagnostics (variable-prefixed abstraction rules such as @{etc_ro}/… are expanded before comparison);
• the event→rule mapping mirrors aa-logprof: log-only c/d file mask characters become w, separate denials on the same path merge into one rule with the combined permissions (an r and a w denial suggest a single rw rule, and w subsumes a), matching fsuid/ouid adds the owner qualifier, denied execs are suggested as ix transitions, hex-encoded paths (e.g. containing spaces) are decoded, and paths are generalised to in-scope tunables: well-known prefixes by pattern (/home/<user> → @{HOME}, /proc/<pid> → @{PROC}/@{pid}, /run/user/<uid> → @{run}/user/@{uid}) plus any path segment equal to a single-value variable's value (e.g. /sys/ → @{sys}), so suggestions match the tunables the profile already includes;
• events from child policy namespaces (e.g. LXD/Docker containers) are ignored, as are denials on disconnected paths (fixed by the attach_disconnected flag, not a rule), hat events when editing the parent profile (and vice versa), and events recorded before the profile file was last modified — an aa-logprof-logmark-style cutoff, so a denial fixed by an earlier edit stops being suggested once the profile is saved.

The log source is auto-detected (/var/log/audit/audit.log when readable, otherwise the journal) and can be pinned with apparmor.auditLog.path — handy for logs copied from another machine. Reading the journal typically requires membership of the adm or systemd-journal group; when running the server from the snap, the log-observe interface must also be connected (see From snap); severity ranking reads the host's /etc/apparmor/severity.db through the automatically connected hostfs-etc-apparmor interface. Set apparmor.auditLog.enable to false to disable the feature entirely.

Architecture

apparmor_language_server/
├── __init__.py         – package metadata
├── __main__.py         – python -m apparmor_language_server entry point
├── server.py           – pygls LSP server, all handler registration
├── indexer.py          – workspace indexer
├── parser.py           – line-oriented AST parser (profiles, rules, …)
├── nodes.py            – AST node dataclasses and visitor utilities (iter_children, walk, NodeVisitor)
├── constants.py        – capabilities, keywords, permissions, abstractions, …
├── render.py           – renders individual AST nodes back to text (RenderOptions, render_node dispatch)
├── completions.py      – context-aware completion provider
├── diagnostics.py      – linting / diagnostic checks
├── code_actions.py     – quick-fix code action provider
├── formatting.py       – AST-driven auto-formatter (returns TextEdits; calls render.py per node)
├── hover.py            – hover documentation provider
├── semantic_tokens.py  – semantic token provider (syntax highlighting)
├── lint.py             – standalone `apparmor-lint` CLI (parser + diagnostics, GCC/JSON output)
├── format.py           – standalone `apparmor-format` CLI (formatter, stdout/in-place/check/diff)
└── docs.py             – helpers for consistent hover/completion docs

Adding a new node type

When a new node type is added to nodes.py, the dispatch tables in hover.py, render.py, and semantic_tokens.py all need a corresponding entry, plus an appropriate implementation function in each file (see sections below).

Adding new checks

Create a new _check_* function in diagnostics.py and call it from _check_node(). Each check receives the AST node and appends Diagnostic objects to the list.

Adding new hover documentation

Add a _hover_<NodeType>(node, line_text, ch) -> Optional[Hover] function in hover.py and register it in the _HOVER_DISPATCH table at the bottom of that file. Variable references (@{VAR}) within any node are resolved before the dispatch, so handlers only need to cover node-specific keywords and fields.

Adding new renderer support

Add a render_<NodeType> function in render.py following the (node, opts: RenderOptions) -> str signature, then register it in the _RENDER_DISPATCH table at the bottom of that file. RenderOptions carries sort (sort parenthesised lists) and file_rule_style.

Adding new semantic token support

Add a _tokens_for_<NodeType> function in semantic_tokens.py following the (node: NodeType) -> list[_Token] signature, then register it in the _DISPATCH table at the bottom of that file. Emit individual tokens with _add(tokens, raw, start_line, offset, length, token_type[, modifiers]). Use RE_ANY_VAR from constants.py to highlight variable and boolean-variable references within values.

Adding new code actions

Add a handler in code_actions.py: check diag.code in get_code_actions(), find the relevant AST node with walk(), and return a CodeAction with a WorkspaceEdit containing the corrective TextEdits.

Adding new completions

Add entries to the relevant _complete_* function in completions.py, or extend the get_completions() dispatcher with a new regex trigger.

Development

# Install dev dependencies (includes pytest, ruff, ty, etc.)
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run tests with coverage, outputting both terminal and JSON reports
pytest --cov=apparmor_language_server --cov-report=term --cov-report=json

# Lint and format
ruff check apparmor_language_server/
ruff format apparmor_language_server/

# Type-check
ty check apparmor_language_server/

# Run the server in TCP mode for interactive debugging
python -m apparmor_language_server --port 2087

Licence

GPL 3.0 or later