TACACS+ TraceId documentation and update HLD by Rod-Persky · Pull Request #2358 · sonic-net/SONiC

Rod-Persky · 2026-06-02T06:25:09Z

Summary

Adds a High-Level Design (HLD) document at doc/aaa/TACACS+ Trace ID.md describing how SONiC propagates a client-supplied SSH TraceId environment variable into TACACS+ command authorization requests issued by bash_tacplus.

Related implementation PR

[tacacs]: Add SSH TraceId authorization attribute sonic-buildimage#27667 — [tacacs]: Add SSH TraceId authorization attribute (the code change implementing this HLD)
[tacacs]: Add SSH TraceId authorization attribute support sonic-host-services#407 — [tacacs]: Add SSH TraceId authorization attribute support

Motivation

Operators routinely need to reconstruct what happened during a specific access session or automation workflow — not just what commands were observed on a device. Today, TACACS+ command authorization records identify the user and command but carry no end-to-end correlation value supplied by the client workflow. This results in disjoint audit trails between the device-side TACACS+ logs and external systems such as access proxies, session recorders, or automation runners.

TraceId provides a shared join key. An access proxy or automation system generates a TraceId, injects it into the SSH session, preserves the same value in its own logs, and SONiC copies the validated value into every TACACS+ command authorization request for that session. A TACACS+ server or downstream log pipeline can then correlate device command authorization records with external access-session, session-recording, incident-response, or automation-run records.

Design overview

SSH client  --SetEnv/SendEnv TraceId-->  sshd (AcceptEnv TraceId)
   --> bash startup marks TraceId readonly
   --> bash_tacplus validates TraceId
   --> tac_add_attrib(&attr, "traceid", trace_id)
   --> TACACS+ authorization server

Standard OpenSSH AcceptEnv is used to receive TraceId; no new SSH client option is introduced.
The user's initial interactive bash shell marks TraceId readonly as a best-effort accidental-change guard (not a security boundary).
bash_tacplus validates the value (length, character set) and either sends the exact value as a traceid=<value> AV pair, or omits the attribute entirely.
Behavior is unchanged when TraceId is absent or invalid, and for all non-authorization TACACS+ flows.

Scope

In scope

Accept an SSH client-supplied TraceId environment variable.
Preserve it as readonly in the initial interactive bash shell.
Validate before attaching to TACACS+ requests.
Add traceid=<value> to TACACS+ command authorization requests only.
Unit, integration, and regression tests for the authorization path.

Out of scope

Other TACACS+ packet types or other AAA flows.
Local Linux audit record changes.
A new ssh -o TraceId=<value> client option.
A tamper-resistant root-owned per-session state store.
SAI, SWSS, syncd, ASIC, or platform driver changes.

Compatibility

SSH login continues to work for clients that do not send TraceId.
TACACS+ servers that ignore unknown AV pairs continue to work unchanged.
Existing TACACS+ server configuration and AAA CLI behavior are untouched.
Existing OpenSSH hardening settings remain intact.

Document

doc/aaa/TACACS+ Trace ID.md — full HLD following the SONiC HLD template (sections 1-16).

Type of change

Documentation (HLD)

This PR is documentation-only; the implementation lives in sonic-net/sonic-buildimage#27667.

linux-foundation-easycla · 2026-06-02T06:25:15Z

The committers listed above are authorized under a signed CLA.

✅ login: Copilot / name: Copilot (8a29686)
✅ login: Rod-Persky / name: Rod Persky (8a29686)

mssonicbld · 2026-06-02T06:25:22Z

/azp run

azure-pipelines · 2026-06-02T06:25:28Z

No pipelines are associated with this pull request.

mssonicbld · 2026-06-02T06:33:44Z

/azp run

azure-pipelines · 2026-06-02T06:33:50Z

No pipelines are associated with this pull request.

…uthorization Implements the HLD in sonic-net/SONiC#2358. Accepts a client-supplied `TraceId` env var via OpenSSH AcceptEnv, marks it readonly in the user's initial interactive bash, validates the value, and attaches it as a `TraceId=<value>` attribute on per-command TACACS+ authorization requests. Behavior is unchanged when TraceId is absent or invalid. How to verify it: - Build sonic-vs and SSH with `SendEnv TraceId` set to a valid value; confirm authorization requests include the TraceId attribute and that invalid/oversized values are silently dropped. - Run the bash_tacplus unit tests under src/tacacs/bash_tacplus/unittest/. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Introduces a High-Level Design for propagating a client-supplied SSH `TraceId` environment variable into TACACS+ command authorization requests issued by `bash_tacplus`. The `TraceId` provides a shared correlation key between external systems (access proxies, automation workflows, session recorders) and per-command TACACS+ authorization records, enabling end-to-end audit trail reconstruction without changing login behavior, TACACS+ server configuration, or command allow/deny semantics. The design accepts `TraceId` via standard OpenSSH `AcceptEnv` propagation, preserves it as a readonly variable in the user's initial interactive shell, validates the value, and attaches it as a `TraceId=<value>` attribute on command authorization requests. Behavior is unchanged when `TraceId` is absent or invalid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

mssonicbld · 2026-06-03T00:25:31Z

/azp run

azure-pipelines · 2026-06-03T00:25:37Z

No pipelines are associated with this pull request.

…uthorization Implements the HLD in sonic-net/SONiC#2358. Accepts a client-supplied `TraceId` env var via OpenSSH AcceptEnv, marks it readonly in the user's initial interactive bash, validates the value, and attaches it as a `TraceId=<value>` attribute on per-command TACACS+ authorization requests. Behavior is unchanged when TraceId is absent or invalid. How to verify it: - Build sonic-vs and SSH with `SendEnv TraceId` set to a valid value; confirm authorization requests include the TraceId attribute and that invalid/oversized values are silently dropped. - Run the bash_tacplus unit tests under src/tacacs/bash_tacplus/unittest/. Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

mssonicbld · 2026-06-10T03:35:08Z

/azp run

azure-pipelines · 2026-06-10T03:35:14Z

No pipelines are associated with this pull request.

tirupatihemanth · 2026-07-07T15:30:33Z

Any plans to show some sort of indication in either CLI (or elsewhere) to indicate that we've TraceId implementation/support present.
NOTE: This is a non-blocker for this HLD approval

sarabjeetsingh1509 · 2026-07-08T04:37:01Z

Hi Rod,

One recommendation is to check if any testcases needs to be added into https://github.com/sonic-net/sonic-mgmt/tree/master/tests/tacacs

Regards

venkatmahalingam · 2026-07-08T05:14:31Z

+This design adds one optional authorization attribute:
+
+```text
+traceid=<trace-id>


What if we don't want to honor the trace-id in the SONiC switch, do we have a config option? I'm thinking from security standpoint.

Hi @venkatmahalingam, I've added yang configuration which is exposed in redis that can be used to disable this feature. This also can be leveraged to identify the feature is available.

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

mssonicbld · 2026-07-09T02:33:40Z

/azp run

azure-pipelines · 2026-07-09T02:33:47Z

No pipelines are associated with this pull request.

Rod-Persky · 2026-07-09T03:43:06Z

@tirupatihemanth, regarding

Any plans to show some sort of indication in either CLI (or elsewhere) to indicate that we've TraceId implementation/support present. NOTE: This is a non-blocker for this HLD approval

I've added yang configuration which is exposed in redis that can be used to identify the feature is available and active.

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

mssonicbld · 2026-07-10T07:35:39Z

/azp run

azure-pipelines · 2026-07-10T07:35:46Z

No pipelines are associated with this pull request.

Rod-Persky force-pushed the dev/rodpersky/tacacs-trace-id branch from e394c2c to 8a29686 Compare June 2, 2026 06:33

Rod-Persky mentioned this pull request Jun 2, 2026

[tacacs]: Add SSH TraceId authorization attribute sonic-net/sonic-buildimage#27667

Open

7 tasks

Rod-Persky marked this pull request as ready for review June 2, 2026 07:30

Rod-Persky force-pushed the dev/rodpersky/tacacs-trace-id branch from 8a29686 to c1eb65c Compare June 3, 2026 00:25

Rename AV pair to traceid to be consistent with AV naming conventions

9bcf62f

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

venkatmahalingam reviewed Jul 8, 2026

View reviewed changes

Reduce some duplication of content and bump version with change log

ff684ff

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

Rod-Persky mentioned this pull request Jul 9, 2026

[tacacs]: Add SSH TraceId authorization attribute support sonic-net/sonic-host-services#407

Open

Added support for | trace id from dotnet

0047c49

Signed-off-by: Rod Persky <770327+Rod-Persky@users.noreply.github.com>

Uh oh!

Conversation

Rod-Persky commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related implementation PR

Motivation

Design overview

Scope

Compatibility

Document

Type of change

Uh oh!

linux-foundation-easycla Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mssonicbld commented Jun 2, 2026

Uh oh!

azure-pipelines Bot commented Jun 2, 2026

Uh oh!

mssonicbld commented Jun 2, 2026

Uh oh!

azure-pipelines Bot commented Jun 2, 2026

Uh oh!

mssonicbld commented Jun 3, 2026

Uh oh!

azure-pipelines Bot commented Jun 3, 2026

Uh oh!

mssonicbld commented Jun 10, 2026

Uh oh!

azure-pipelines Bot commented Jun 10, 2026

Uh oh!

tirupatihemanth commented Jul 7, 2026

Uh oh!

sarabjeetsingh1509 commented Jul 8, 2026

Uh oh!

venkatmahalingam Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Rod-Persky Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

mssonicbld commented Jul 9, 2026

Uh oh!

azure-pipelines Bot commented Jul 9, 2026

Uh oh!

Rod-Persky commented Jul 9, 2026

Uh oh!

mssonicbld commented Jul 10, 2026

Uh oh!

azure-pipelines Bot commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Rod-Persky commented Jun 2, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Jun 2, 2026 •

edited

Loading