High-level facade for emitting ATNA audit events from DICOM services. More...

#include <atna_service_auditor.h>

Collaboration diagram for kcenon::pacs::security::atna_service_auditor:

Public Types
enum class	xds_source_transaction : uint8_t { iti_41 , rad_68 }
	XDS-I.b source-side transaction identifier. More...

enum class	xds_consumer_transaction : uint8_t { iti_43 , rad_69 }
	XDS-I.b consumer-side transaction identifier. More...

Public Member Functions
	atna_service_auditor (const syslog_transport_config &config, std::string audit_source_id)
	Construct an auditor with syslog transport configuration.

virtual	~atna_service_auditor ()=default

	atna_service_auditor (const atna_service_auditor &)=delete

atna_service_auditor &	operator= (const atna_service_auditor &)=delete

	atna_service_auditor (atna_service_auditor &&) noexcept

atna_service_auditor &	operator= (atna_service_auditor &&) noexcept

void	audit_instance_stored (const std::string &source_ae, const std::string &dest_ae, const std::string &study_uid, const std::string &patient_id, bool success)
	Audit a C-STORE (DICOM Instances Transferred) event.

void	audit_query (const std::string &calling_ae, const std::string &called_ae, const std::string &query_level, bool success)
	Audit a C-FIND (Query) event.

void	audit_authentication (const std::string &user_id, bool is_login, bool success)
	Audit a User Authentication event.

void	audit_security_alert (const std::string &user_id, const std::string &alert_description)
	Audit a Security Alert event (e.g., access denied)

virtual void	audit_xds_provide_and_register (xds_source_transaction transaction, const std::string &source_ae, const std::string &dest_ae, const std::string &study_uid, const std::string &patient_id, const std::vector< std::string > &sop_instance_uids, bool success)
	Audit an XDS-I.b Provide and Register Document Set transaction.

virtual void	audit_xds_retrieve (xds_consumer_transaction transaction, const std::string &source_ae, const std::string &dest_ae, const std::string &study_uid, const std::string &patient_id, const std::vector< std::string > &sop_instance_uids, bool success)
	Audit an XDS-I.b Retrieve Document Set transaction.

void	set_enabled (bool enabled) noexcept
	Enable or disable audit event emission.

bool	is_enabled () const noexcept
	Check if audit event emission is enabled.

size_t	events_sent () const noexcept
	Get the number of audit events successfully sent.

size_t	events_failed () const noexcept
	Get the number of audit event send failures.

void	reset_statistics () noexcept
	Reset statistics counters.

const std::string &	audit_source_id () const noexcept
	Get the audit source identifier.

const atna_syslog_transport &	transport () const noexcept
	Get the underlying transport (for advanced use)

void	submit_audit_message (const atna_audit_message &message)
	Emit a pre-built RFC 3881 audit message.

Private Member Functions
void	send_audit (const atna_audit_message &message)
	Send an audit message via syslog transport.

Private Attributes
std::string	audit_source_id_
	Audit source identifier (e.g., "PACS_SYSTEM_01")

atna_syslog_transport	transport_
	Syslog transport for sending audit messages.

std::atomic< bool >	enabled_ {true}
	Whether audit is enabled.

std::atomic< size_t >	events_sent_ {0}
	Statistics.

std::atomic< size_t >	events_failed_ {0}

Detailed Description

High-level facade for emitting ATNA audit events from DICOM services.

Combines the audit message generator (atna_audit_logger) with the syslog transport (atna_syslog_transport) to provide simple, one-call audit methods for common DICOM operations.

Usage

syslog_transport_config config;
config.host = "audit-server.hospital.local";
config.port = 6514;
config.protocol = syslog_transport_protocol::tls;
 
atna_service_auditor auditor(config, "PACS_SYSTEM_01");
 
// After a C-STORE operation:
auditor.audit_instance_stored("MODALITY_01", "PACS_SCP",
    "1.2.3.4.5", "PAT001", true);
 
// After a C-FIND operation:
auditor.audit_query("WORKSTATION_01", "PACS_SCP",
    "STUDY", true);

Definition at line 54 of file atna_service_auditor.h.

Member Enumeration Documentation

◆ xds_consumer_transaction

enum class kcenon::pacs::security::atna_service_auditor::xds_consumer_transaction : uint8_t

strong

XDS-I.b consumer-side transaction identifier.

Used by audit_xds_retrieve() to distinguish between ITI-43 (general document retrieval) and RAD-69 (imaging document retrieval) transactions.

Enumerator
iti_43	ITI-43 Retrieve Document Set.
rad_69	RAD-69 Retrieve Imaging Document Set.

Definition at line 152 of file atna_service_auditor.h.

                                        : uint8_t {
        iti_43,   
        rad_69    
    };

◆ xds_source_transaction

enum class kcenon::pacs::security::atna_service_auditor::xds_source_transaction : uint8_t

strong

XDS-I.b source-side transaction identifier.

Used by audit_xds_provide_and_register() to distinguish between ITI-41 (general document set) and RAD-68 (imaging document set) transactions.

Enumerator
iti_41	ITI-41 Provide and Register Document Set-b.
rad_68	RAD-68 Provide and Register Imaging Document Set.

Definition at line 140 of file atna_service_auditor.h.

                                      : uint8_t {
        iti_41,   
        rad_68    
    };

Constructor & Destructor Documentation

◆ atna_service_auditor() [1/3]

kcenon::pacs::security::atna_service_auditor::atna_service_auditor	(	const syslog_transport_config &	config,
		std::string	audit_source_id )

Construct an auditor with syslog transport configuration.

Parameters

config	Syslog transport configuration
audit_source_id	Identifier for this audit source (e.g., "PACS_01")

Definition at line 14 of file atna_service_auditor.cpp.

17 : audit_source_id_(std::move(audit_source_id)),

18 transport_(config) {}

kcenon::pacs::security::atna_service_auditor::audit_source_id_

std::string audit_source_id_

Audit source identifier (e.g., "PACS_SYSTEM_01")

Definition atna_service_auditor.h:300

kcenon::pacs::security::atna_service_auditor::audit_source_id

const std::string & audit_source_id() const noexcept

Get the audit source identifier.

Definition atna_service_auditor.cpp:295

kcenon::pacs::security::atna_service_auditor::transport_

atna_syslog_transport transport_

Syslog transport for sending audit messages.

Definition atna_service_auditor.h:303

◆ ~atna_service_auditor()

virtual kcenon::pacs::security::atna_service_auditor::~atna_service_auditor ( )

virtualdefault

◆ atna_service_auditor() [2/3]

kcenon::pacs::security::atna_service_auditor::atna_service_auditor ( const atna_service_auditor & )

delete

◆ atna_service_auditor() [3/3]

kcenon::pacs::security::atna_service_auditor::atna_service_auditor ( atna_service_auditor && other )

noexcept

Definition at line 20 of file atna_service_auditor.cpp.

    : audit_source_id_(std::move(other.audit_source_id_)),
      transport_(std::move(other.transport_)),
      enabled_(other.enabled_.load(std::memory_order_relaxed)),
      events_sent_(other.events_sent_.load(std::memory_order_relaxed)),
      events_failed_(other.events_failed_.load(std::memory_order_relaxed)) {}

Member Function Documentation

◆ audit_authentication()

void kcenon::pacs::security::atna_service_auditor::audit_authentication	(	const std::string &	user_id,
		bool	is_login,
		bool	success )

Audit a User Authentication event.

Parameters

user_id	User identifier (AE title or username)
is_login	true for login, false for logout
success	Whether the authentication succeeded

Definition at line 101 of file atna_service_auditor.cpp.

                  {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto outcome = success ? atna_event_outcome::success
                           : atna_event_outcome::serious_failure;
 
    auto msg = atna_audit_logger::build_user_authentication(
        audit_source_id_,
        user_id,
        "",           // user IP (not available at this level)
        is_login,
        outcome);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_user_authentication(), enabled_, send_audit(), kcenon::pacs::security::serious_failure, and kcenon::pacs::security::success.

Here is the call graph for this function:

◆ audit_instance_stored()

void kcenon::pacs::security::atna_service_auditor::audit_instance_stored	(	const std::string &	source_ae,
		const std::string &	dest_ae,
		const std::string &	study_uid,
		const std::string &	patient_id,
		bool	success )

Audit a C-STORE (DICOM Instances Transferred) event.

Parameters

source_ae	Calling AE title (sender)
dest_ae	Called AE title (receiver)
study_uid	Study Instance UID
patient_id	Patient ID (optional, empty if unavailable)
success	Whether the operation succeeded

Definition at line 48 of file atna_service_auditor.cpp.

                  {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto outcome = success ? atna_event_outcome::success
                           : atna_event_outcome::serious_failure;
 
    auto msg = atna_audit_logger::build_dicom_instances_transferred(
        audit_source_id_,
        source_ae,    // source AE
        "",           // source IP (not available at service level)
        dest_ae,      // destination AE
        "",           // destination IP (not available at service level)
        study_uid,
        patient_id,
        true,         // is_import (SCP receiving)
        outcome);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_dicom_instances_transferred(), enabled_, send_audit(), kcenon::pacs::security::serious_failure, and kcenon::pacs::security::success.

Referenced by kcenon::pacs::services::storage_scp::handle_message().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ audit_query()

void kcenon::pacs::security::atna_service_auditor::audit_query	(	const std::string &	calling_ae,
		const std::string &	called_ae,
		const std::string &	query_level,
		bool	success )

Audit a C-FIND (Query) event.

Parameters

calling_ae	Calling AE title (query requester)
called_ae	Called AE title (query responder)
query_level	Query level string (PATIENT/STUDY/SERIES/IMAGE)
success	Whether the operation succeeded

Definition at line 76 of file atna_service_auditor.cpp.

                  {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto outcome = success ? atna_event_outcome::success
                           : atna_event_outcome::serious_failure;
 
    // Use query level as query_data for the audit trail
    auto msg = atna_audit_logger::build_query(
        audit_source_id_,
        calling_ae,
        "",           // user IP (not available at service level)
        "QueryLevel=" + query_level + " CalledAE=" + called_ae,
        "",           // patient_id (not available from query keys here)
        outcome);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_query(), enabled_, send_audit(), kcenon::pacs::security::serious_failure, and kcenon::pacs::security::success.

Referenced by kcenon::pacs::services::query_scp::handle_message().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ audit_security_alert()

void kcenon::pacs::security::atna_service_auditor::audit_security_alert	(	const std::string &	user_id,
		const std::string &	alert_description )

Audit a Security Alert event (e.g., access denied)

Parameters

user_id	User identifier
alert_description	Description of the security alert

Definition at line 123 of file atna_service_auditor.cpp.

                                        {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto msg = atna_audit_logger::build_security_alert(
        audit_source_id_,
        user_id,
        "",           // user IP (not available at this level)
        alert_description);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_security_alert(), enabled_, and send_audit().

Here is the call graph for this function:

◆ audit_source_id()

const std::string & kcenon::pacs::security::atna_service_auditor::audit_source_id ( ) const

nodiscardnoexcept

Get the audit source identifier.

Definition at line 295 of file atna_service_auditor.cpp.

                                                                      {
    return audit_source_id_;
}

References audit_source_id_.

◆ audit_xds_provide_and_register()

void kcenon::pacs::security::atna_service_auditor::audit_xds_provide_and_register	(	xds_source_transaction	transaction,
		const std::string &	source_ae,
		const std::string &	dest_ae,
		const std::string &	study_uid,
		const std::string &	patient_id,
		const std::vector< std::string > &	sop_instance_uids,
		bool	success )

virtual

Audit an XDS-I.b Provide and Register Document Set transaction.

Emits an Export (DCM 110106) audit event for source-side XDS transactions (ITI-41 / RAD-68). The transaction identifier is recorded as an event type code to distinguish ITI-41 from RAD-68.

Parameters

transaction	Transaction identifier (ITI-41 or RAD-68)
source_ae	Local source participant (AE / device identifier)
dest_ae	Remote destination participant (XDS registry/repository)
study_uid	Study Instance UID (the study being provided)
patient_id	Patient ID (optional, empty if unavailable)
sop_instance_uids	Referenced SOP Instance UIDs (may be empty for ITI-41)
success	Whether the transaction succeeded

Definition at line 178 of file atna_service_auditor.cpp.

                  {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto outcome = success ? atna_event_outcome::success
                           : atna_event_outcome::serious_failure;
 
    // XDS-I.b Provide and Register is an Export event (DCM 110106) —
    // the local actor is sending a document set to a remote registry.
    auto msg = atna_audit_logger::build_export(
        audit_source_id_,
        source_ae,   // user (the local source actor)
        "",          // user IP (not available at service level)
        dest_ae,     // destination identifier (remote registry)
        study_uid,
        patient_id,
        outcome);
 
    // Tag the event with the specific IHE transaction code so consumers
    // of the audit log can differentiate ITI-41 from RAD-68.
    msg.event_type_codes.push_back(
        transaction == xds_source_transaction::iti_41
            ? xds_event_type_iti_41
            : xds_event_type_rad_68);
 
    // Add SOP Instance UID references if provided (required for RAD-68,
    // optional but recommended for ITI-41).
    append_sop_instance_objects(msg, sop_instance_uids);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_export(), enabled_, iti_41, send_audit(), kcenon::pacs::security::serious_failure, and kcenon::pacs::security::success.

Referenced by kcenon::pacs::services::xds::imaging_document_source::publish_document().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ audit_xds_retrieve()

void kcenon::pacs::security::atna_service_auditor::audit_xds_retrieve	(	xds_consumer_transaction	transaction,
		const std::string &	source_ae,
		const std::string &	dest_ae,
		const std::string &	study_uid,
		const std::string &	patient_id,
		const std::vector< std::string > &	sop_instance_uids,
		bool	success )

virtual

Audit an XDS-I.b Retrieve Document Set transaction.

Emits an Import (DCM 110107, via DICOM Instances Transferred) audit event for consumer-side XDS transactions (ITI-43 / RAD-69). The transaction identifier is recorded as an event type code.

Parameters

transaction	Transaction identifier (ITI-43 or RAD-69)
source_ae	Remote source participant (XDS repository)
dest_ae	Local destination participant (this consumer)
study_uid	Study Instance UID (the study being retrieved)
patient_id	Patient ID (optional, empty if unavailable)
sop_instance_uids	Referenced SOP Instance UIDs (may be empty)
success	Whether the transaction succeeded

Definition at line 219 of file atna_service_auditor.cpp.

                  {
 
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
 
    auto outcome = success ? atna_event_outcome::success
                           : atna_event_outcome::serious_failure;
 
    // XDS-I.b Retrieve Document Set is an Import event
    // (DICOM Instances Transferred with is_import=true) — the local
    // actor is receiving a document set from a remote repository.
    auto msg = atna_audit_logger::build_dicom_instances_transferred(
        audit_source_id_,
        source_ae,
        "",          // source IP (not available at service level)
        dest_ae,
        "",          // destination IP (not available at service level)
        study_uid,
        patient_id,
        true,        // is_import (consumer is receiving)
        outcome);
 
    // Tag the event with the specific IHE transaction code so consumers
    // of the audit log can differentiate ITI-43 from RAD-69.
    msg.event_type_codes.push_back(
        transaction == xds_consumer_transaction::iti_43
            ? xds_event_type_iti_43
            : xds_event_type_rad_69);
 
    // Add SOP Instance UID references if provided.
    append_sop_instance_objects(msg, sop_instance_uids);
 
    send_audit(msg);
}

References audit_source_id_, kcenon::pacs::security::atna_audit_logger::build_dicom_instances_transferred(), enabled_, iti_43, send_audit(), kcenon::pacs::security::serious_failure, and kcenon::pacs::security::success.

Referenced by kcenon::pacs::services::xds::imaging_document_consumer::retrieve_document().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ events_failed()

size_t kcenon::pacs::security::atna_service_auditor::events_failed ( ) const

nodiscardnoexcept

Get the number of audit event send failures.

Definition at line 282 of file atna_service_auditor.cpp.

                                                          {
    return events_failed_.load(std::memory_order_relaxed);
}

References events_failed_.

◆ events_sent()

size_t kcenon::pacs::security::atna_service_auditor::events_sent ( ) const

nodiscardnoexcept

Get the number of audit events successfully sent.

Definition at line 278 of file atna_service_auditor.cpp.

                                                        {
    return events_sent_.load(std::memory_order_relaxed);
}

References events_sent_.

◆ is_enabled()

bool kcenon::pacs::security::atna_service_auditor::is_enabled ( ) const

nodiscardnoexcept

Check if audit event emission is enabled.

Returns: true if enabled

Definition at line 270 of file atna_service_auditor.cpp.

                                                     {
    return enabled_.load(std::memory_order_relaxed);
}

References enabled_.

◆ operator=() [1/2]

atna_service_auditor & kcenon::pacs::security::atna_service_auditor::operator= ( atna_service_auditor && other )

noexcept

Definition at line 28 of file atna_service_auditor.cpp.

                                           {
    if (this != &other) {
        audit_source_id_ = std::move(other.audit_source_id_);
        transport_ = std::move(other.transport_);
        enabled_.store(other.enabled_.load(std::memory_order_relaxed),
                       std::memory_order_relaxed);
        events_sent_.store(other.events_sent_.load(std::memory_order_relaxed),
                           std::memory_order_relaxed);
        events_failed_.store(
            other.events_failed_.load(std::memory_order_relaxed),
            std::memory_order_relaxed);
    }
    return *this;
}

References kcenon::pacs::security::other.

◆ operator=() [2/2]

atna_service_auditor & kcenon::pacs::security::atna_service_auditor::operator= ( const atna_service_auditor & )

delete

◆ reset_statistics()

void kcenon::pacs::security::atna_service_auditor::reset_statistics ( )

noexcept

Reset statistics counters.

Definition at line 286 of file atna_service_auditor.cpp.

                                                     {
    events_sent_.store(0, std::memory_order_relaxed);
    events_failed_.store(0, std::memory_order_relaxed);
}

References events_failed_, and events_sent_.

◆ send_audit()

void kcenon::pacs::security::atna_service_auditor::send_audit ( const atna_audit_message & message )

private

Send an audit message via syslog transport.

Converts the message to XML and sends it. Updates statistics.

Parameters

message The audit message to send

Definition at line 315 of file atna_service_auditor.cpp.

                                                                       {
    auto xml = atna_audit_logger::to_xml(message);
    auto result = transport_.send(xml);
 
    if (result.is_ok()) {
        events_sent_.fetch_add(1, std::memory_order_relaxed);
    } else {
        events_failed_.fetch_add(1, std::memory_order_relaxed);
    }
}

References events_failed_, events_sent_, kcenon::pacs::security::atna_syslog_transport::send(), kcenon::pacs::security::atna_audit_logger::to_xml(), and transport_.

Referenced by audit_authentication(), audit_instance_stored(), audit_query(), audit_security_alert(), audit_xds_provide_and_register(), audit_xds_retrieve(), and submit_audit_message().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_enabled()

void kcenon::pacs::security::atna_service_auditor::set_enabled ( bool enabled )

noexcept

Enable or disable audit event emission.

When disabled, audit methods return immediately without generating or sending any messages. Useful for testing or low-resource environments.

Parameters

enabled true to enable, false to disable

Definition at line 266 of file atna_service_auditor.cpp.

                                                            {
    enabled_.store(enabled, std::memory_order_relaxed);
}

◆ submit_audit_message()

void kcenon::pacs::security::atna_service_auditor::submit_audit_message ( const atna_audit_message & message )

Emit a pre-built RFC 3881 audit message.

Allows callers with their own transaction-specific event code and EventTypeCode vocabulary (e.g., the XDS.b actors under xds_audit_events.h) to route a fully-formed message through the auditor's serialized transport and statistics path instead of opening a second socket. Respects the enabled() flag and updates the same events_sent/events_failed counters as the high-level audit_* methods.

Thread safety: safe to call concurrently - delegation is through the same private send_audit() path as all other audit_* methods.

Parameters

message The audit message to serialize and send.

See also: Issue #1131

Definition at line 303 of file atna_service_auditor.cpp.

                                       {
    if (!enabled_.load(std::memory_order_relaxed)) {
        return;
    }
    send_audit(message);
}

References enabled_, and send_audit().

Here is the call graph for this function:

◆ transport()

const atna_syslog_transport & kcenon::pacs::security::atna_service_auditor::transport ( ) const

nodiscardnoexcept

Get the underlying transport (for advanced use)

Definition at line 299 of file atna_service_auditor.cpp.

                                                                            {
    return transport_;
}

References transport_.

Member Data Documentation

◆ audit_source_id_

std::string kcenon::pacs::security::atna_service_auditor::audit_source_id_

private

Audit source identifier (e.g., "PACS_SYSTEM_01")

Definition at line 300 of file atna_service_auditor.h.

Referenced by audit_authentication(), audit_instance_stored(), audit_query(), audit_security_alert(), audit_source_id(), audit_xds_provide_and_register(), and audit_xds_retrieve().

◆ enabled_

std::atomic<bool> kcenon::pacs::security::atna_service_auditor::enabled_ {true}

private

Whether audit is enabled.

Definition at line 306 of file atna_service_auditor.h.

306{true};

Referenced by audit_authentication(), audit_instance_stored(), audit_query(), audit_security_alert(), audit_xds_provide_and_register(), audit_xds_retrieve(), is_enabled(), and submit_audit_message().

◆ events_failed_

std::atomic<size_t> kcenon::pacs::security::atna_service_auditor::events_failed_ {0}

private

Definition at line 310 of file atna_service_auditor.h.

310{0};

Referenced by events_failed(), reset_statistics(), and send_audit().

◆ events_sent_

std::atomic<size_t> kcenon::pacs::security::atna_service_auditor::events_sent_ {0}

private

Statistics.

Definition at line 309 of file atna_service_auditor.h.

309{0};

Referenced by events_sent(), reset_statistics(), and send_audit().

◆ transport_

atna_syslog_transport kcenon::pacs::security::atna_service_auditor::transport_

private

Syslog transport for sending audit messages.

Definition at line 303 of file atna_service_auditor.h.

Referenced by send_audit(), and transport().

The documentation for this class was generated from the following files:

include/kcenon/pacs/security/atna_service_auditor.h
src/security/atna_service_auditor.cpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Usage

Member Enumeration Documentation

◆ xds_consumer_transaction

◆ xds_source_transaction

Constructor & Destructor Documentation

◆ atna_service_auditor() [1/3]

◆ ~atna_service_auditor()

◆ atna_service_auditor() [2/3]

◆ atna_service_auditor() [3/3]

Member Function Documentation

◆ audit_authentication()

◆ audit_instance_stored()

◆ audit_query()

◆ audit_security_alert()

◆ audit_source_id()

◆ audit_xds_provide_and_register()

◆ audit_xds_retrieve()

◆ events_failed()

◆ events_sent()

◆ is_enabled()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ reset_statistics()

◆ send_audit()

◆ set_enabled()

◆ submit_audit_message()

◆ transport()

Member Data Documentation

◆ audit_source_id_

◆ enabled_

◆ events_failed_

◆ events_sent_

◆ transport_