datasynth_core/models/
coso.rs

1//! COSO 2013 Internal Control-Integrated Framework definitions.
2//!
3//! Provides structures for modeling the COSO framework's 5 components
4//! and 17 principles, along with control scope and maturity levels.
5
6use serde::{Deserialize, Serialize};
7
8/// COSO 2013 Framework - 5 Components of Internal Control.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum CosoComponent {
12    /// The set of standards, processes, and structures that provide the basis
13    /// for carrying out internal control across the organization.
14    ControlEnvironment,
15    /// A dynamic and iterative process for identifying and assessing risks
16    /// to achievement of objectives.
17    RiskAssessment,
18    /// Actions established through policies and procedures that help ensure
19    /// that management's directives are carried out.
20    ControlActivities,
21    /// Information is necessary for the entity to carry out internal control
22    /// responsibilities. Communication is the ongoing process of providing,
23    /// sharing, and obtaining necessary information.
24    InformationCommunication,
25    /// Ongoing evaluations, separate evaluations, or some combination of
26    /// the two are used to ascertain whether each of the five components
27    /// of internal control is present and functioning.
28    MonitoringActivities,
29}
30
31impl std::fmt::Display for CosoComponent {
32    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
33        match self {
34            Self::ControlEnvironment => write!(f, "Control Environment"),
35            Self::RiskAssessment => write!(f, "Risk Assessment"),
36            Self::ControlActivities => write!(f, "Control Activities"),
37            Self::InformationCommunication => write!(f, "Information & Communication"),
38            Self::MonitoringActivities => write!(f, "Monitoring Activities"),
39        }
40    }
41}
42
43/// COSO 2013 Framework - 17 Principles of Internal Control.
44///
45/// Each principle maps to one of the 5 COSO components:
46/// - Control Environment: Principles 1-5
47/// - Risk Assessment: Principles 6-9
48/// - Control Activities: Principles 10-12
49/// - Information & Communication: Principles 13-15
50/// - Monitoring Activities: Principles 16-17
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
52#[serde(rename_all = "snake_case")]
53pub enum CosoPrinciple {
54    // Control Environment (Principles 1-5)
55    /// Principle 1: The organization demonstrates a commitment to integrity
56    /// and ethical values.
57    IntegrityAndEthics,
58    /// Principle 2: The board of directors demonstrates independence from
59    /// management and exercises oversight of internal control.
60    BoardOversight,
61    /// Principle 3: Management establishes structures, reporting lines, and
62    /// appropriate authorities and responsibilities.
63    OrganizationalStructure,
64    /// Principle 4: The organization demonstrates a commitment to attract,
65    /// develop, and retain competent individuals.
66    CommitmentToCompetence,
67    /// Principle 5: The organization holds individuals accountable for their
68    /// internal control responsibilities.
69    Accountability,
70
71    // Risk Assessment (Principles 6-9)
72    /// Principle 6: The organization specifies objectives with sufficient
73    /// clarity to enable the identification and assessment of risks.
74    ClearObjectives,
75    /// Principle 7: The organization identifies risks to the achievement
76    /// of its objectives and analyzes risks as a basis for determining
77    /// how the risks should be managed.
78    IdentifyRisks,
79    /// Principle 8: The organization considers the potential for fraud
80    /// in assessing risks to the achievement of objectives.
81    FraudRisk,
82    /// Principle 9: The organization identifies and assesses changes that
83    /// could significantly impact the system of internal control.
84    ChangeIdentification,
85
86    // Control Activities (Principles 10-12)
87    /// Principle 10: The organization selects and develops control activities
88    /// that contribute to the mitigation of risks.
89    ControlActions,
90    /// Principle 11: The organization selects and develops general control
91    /// activities over technology to support the achievement of objectives.
92    TechnologyControls,
93    /// Principle 12: The organization deploys control activities through
94    /// policies that establish what is expected and procedures that put
95    /// policies into action.
96    PoliciesAndProcedures,
97
98    // Information & Communication (Principles 13-15)
99    /// Principle 13: The organization obtains or generates and uses relevant,
100    /// quality information to support the functioning of internal control.
101    QualityInformation,
102    /// Principle 14: The organization internally communicates information,
103    /// including objectives and responsibilities for internal control.
104    InternalCommunication,
105    /// Principle 15: The organization communicates with external parties
106    /// regarding matters affecting the functioning of internal control.
107    ExternalCommunication,
108
109    // Monitoring Activities (Principles 16-17)
110    /// Principle 16: The organization selects, develops, and performs ongoing
111    /// and/or separate evaluations to ascertain whether the components of
112    /// internal control are present and functioning.
113    OngoingMonitoring,
114    /// Principle 17: The organization evaluates and communicates internal
115    /// control deficiencies in a timely manner to those parties responsible
116    /// for taking corrective action.
117    DeficiencyEvaluation,
118}
119
120impl CosoPrinciple {
121    /// Returns the COSO component that this principle belongs to.
122    pub fn component(&self) -> CosoComponent {
123        match self {
124            // Control Environment (Principles 1-5)
125            Self::IntegrityAndEthics
126            | Self::BoardOversight
127            | Self::OrganizationalStructure
128            | Self::CommitmentToCompetence
129            | Self::Accountability => CosoComponent::ControlEnvironment,
130
131            // Risk Assessment (Principles 6-9)
132            Self::ClearObjectives
133            | Self::IdentifyRisks
134            | Self::FraudRisk
135            | Self::ChangeIdentification => CosoComponent::RiskAssessment,
136
137            // Control Activities (Principles 10-12)
138            Self::ControlActions | Self::TechnologyControls | Self::PoliciesAndProcedures => {
139                CosoComponent::ControlActivities
140            }
141
142            // Information & Communication (Principles 13-15)
143            Self::QualityInformation
144            | Self::InternalCommunication
145            | Self::ExternalCommunication => CosoComponent::InformationCommunication,
146
147            // Monitoring Activities (Principles 16-17)
148            Self::OngoingMonitoring | Self::DeficiencyEvaluation => {
149                CosoComponent::MonitoringActivities
150            }
151        }
152    }
153
154    /// Returns the principle number (1-17) in the COSO framework.
155    pub fn principle_number(&self) -> u8 {
156        match self {
157            Self::IntegrityAndEthics => 1,
158            Self::BoardOversight => 2,
159            Self::OrganizationalStructure => 3,
160            Self::CommitmentToCompetence => 4,
161            Self::Accountability => 5,
162            Self::ClearObjectives => 6,
163            Self::IdentifyRisks => 7,
164            Self::FraudRisk => 8,
165            Self::ChangeIdentification => 9,
166            Self::ControlActions => 10,
167            Self::TechnologyControls => 11,
168            Self::PoliciesAndProcedures => 12,
169            Self::QualityInformation => 13,
170            Self::InternalCommunication => 14,
171            Self::ExternalCommunication => 15,
172            Self::OngoingMonitoring => 16,
173            Self::DeficiencyEvaluation => 17,
174        }
175    }
176}
177
178impl std::fmt::Display for CosoPrinciple {
179    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
180        match self {
181            Self::IntegrityAndEthics => write!(f, "Integrity and Ethics"),
182            Self::BoardOversight => write!(f, "Board Oversight"),
183            Self::OrganizationalStructure => write!(f, "Organizational Structure"),
184            Self::CommitmentToCompetence => write!(f, "Commitment to Competence"),
185            Self::Accountability => write!(f, "Accountability"),
186            Self::ClearObjectives => write!(f, "Clear Objectives"),
187            Self::IdentifyRisks => write!(f, "Identify Risks"),
188            Self::FraudRisk => write!(f, "Fraud Risk"),
189            Self::ChangeIdentification => write!(f, "Change Identification"),
190            Self::ControlActions => write!(f, "Control Actions"),
191            Self::TechnologyControls => write!(f, "Technology Controls"),
192            Self::PoliciesAndProcedures => write!(f, "Policies and Procedures"),
193            Self::QualityInformation => write!(f, "Quality Information"),
194            Self::InternalCommunication => write!(f, "Internal Communication"),
195            Self::ExternalCommunication => write!(f, "External Communication"),
196            Self::OngoingMonitoring => write!(f, "Ongoing Monitoring"),
197            Self::DeficiencyEvaluation => write!(f, "Deficiency Evaluation"),
198        }
199    }
200}
201
202/// Control scope distinguishing entity-level from transaction-level controls.
203#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
204#[serde(rename_all = "snake_case")]
205pub enum ControlScope {
206    /// Entity-level controls operate across the organization and are typically
207    /// more pervasive in nature (e.g., tone at the top, code of conduct).
208    EntityLevel,
209    /// Transaction-level controls operate at the process or transaction level
210    /// and are typically more specific (e.g., three-way match, approvals).
211    TransactionLevel,
212    /// IT General Controls (ITGCs) are controls over the IT environment that
213    /// support the effective functioning of application controls.
214    ItGeneralControl,
215    /// IT Application Controls are automated controls embedded within
216    /// applications to ensure data integrity and proper authorization.
217    ItApplicationControl,
218}
219
220impl std::fmt::Display for ControlScope {
221    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
222        match self {
223            Self::EntityLevel => write!(f, "Entity Level"),
224            Self::TransactionLevel => write!(f, "Transaction Level"),
225            Self::ItGeneralControl => write!(f, "IT General Control"),
226            Self::ItApplicationControl => write!(f, "IT Application Control"),
227        }
228    }
229}
230
231/// Control maturity level based on capability maturity models.
232#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
233#[serde(rename_all = "snake_case")]
234pub enum CosoMaturityLevel {
235    /// Level 0: Control processes do not exist or are not recognized.
236    NonExistent,
237    /// Level 1: Processes are ad hoc and chaotic; success depends on
238    /// individual effort.
239    AdHoc,
240    /// Level 2: Basic processes exist and are repeated; discipline exists
241    /// to maintain basic consistency.
242    Repeatable,
243    /// Level 3: Processes are documented, standardized, and integrated
244    /// into the organization.
245    Defined,
246    /// Level 4: Processes are measured and controlled using metrics;
247    /// performance is predictable.
248    Managed,
249    /// Level 5: Continuous improvement is enabled through feedback and
250    /// innovative ideas.
251    Optimized,
252}
253
254impl std::fmt::Display for CosoMaturityLevel {
255    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
256        match self {
257            Self::NonExistent => write!(f, "Non-Existent"),
258            Self::AdHoc => write!(f, "Ad Hoc"),
259            Self::Repeatable => write!(f, "Repeatable"),
260            Self::Defined => write!(f, "Defined"),
261            Self::Managed => write!(f, "Managed"),
262            Self::Optimized => write!(f, "Optimized"),
263        }
264    }
265}
266
267impl CosoMaturityLevel {
268    /// Returns the numeric level (0-5).
269    pub fn level(&self) -> u8 {
270        match self {
271            Self::NonExistent => 0,
272            Self::AdHoc => 1,
273            Self::Repeatable => 2,
274            Self::Defined => 3,
275            Self::Managed => 4,
276            Self::Optimized => 5,
277        }
278    }
279}
280
281#[cfg(test)]
282mod tests {
283    use super::*;
284
285    #[test]
286    fn test_principle_component_mapping() {
287        // Control Environment principles
288        assert_eq!(
289            CosoPrinciple::IntegrityAndEthics.component(),
290            CosoComponent::ControlEnvironment
291        );
292        assert_eq!(
293            CosoPrinciple::Accountability.component(),
294            CosoComponent::ControlEnvironment
295        );
296
297        // Risk Assessment principles
298        assert_eq!(
299            CosoPrinciple::FraudRisk.component(),
300            CosoComponent::RiskAssessment
301        );
302
303        // Control Activities principles
304        assert_eq!(
305            CosoPrinciple::ControlActions.component(),
306            CosoComponent::ControlActivities
307        );
308        assert_eq!(
309            CosoPrinciple::TechnologyControls.component(),
310            CosoComponent::ControlActivities
311        );
312
313        // Information & Communication principles
314        assert_eq!(
315            CosoPrinciple::QualityInformation.component(),
316            CosoComponent::InformationCommunication
317        );
318
319        // Monitoring Activities principles
320        assert_eq!(
321            CosoPrinciple::OngoingMonitoring.component(),
322            CosoComponent::MonitoringActivities
323        );
324        assert_eq!(
325            CosoPrinciple::DeficiencyEvaluation.component(),
326            CosoComponent::MonitoringActivities
327        );
328    }
329
330    #[test]
331    fn test_principle_numbers() {
332        assert_eq!(CosoPrinciple::IntegrityAndEthics.principle_number(), 1);
333        assert_eq!(CosoPrinciple::Accountability.principle_number(), 5);
334        assert_eq!(CosoPrinciple::ClearObjectives.principle_number(), 6);
335        assert_eq!(CosoPrinciple::ControlActions.principle_number(), 10);
336        assert_eq!(CosoPrinciple::QualityInformation.principle_number(), 13);
337        assert_eq!(CosoPrinciple::DeficiencyEvaluation.principle_number(), 17);
338    }
339
340    #[test]
341    fn test_maturity_level_ordering() {
342        assert!(CosoMaturityLevel::NonExistent < CosoMaturityLevel::AdHoc);
343        assert!(CosoMaturityLevel::AdHoc < CosoMaturityLevel::Repeatable);
344        assert!(CosoMaturityLevel::Repeatable < CosoMaturityLevel::Defined);
345        assert!(CosoMaturityLevel::Defined < CosoMaturityLevel::Managed);
346        assert!(CosoMaturityLevel::Managed < CosoMaturityLevel::Optimized);
347    }
348
349    #[test]
350    fn test_maturity_level_numeric() {
351        assert_eq!(CosoMaturityLevel::NonExistent.level(), 0);
352        assert_eq!(CosoMaturityLevel::Optimized.level(), 5);
353    }
354
355    #[test]
356    fn test_display_implementations() {
357        assert_eq!(
358            CosoComponent::ControlEnvironment.to_string(),
359            "Control Environment"
360        );
361        assert_eq!(
362            CosoPrinciple::IntegrityAndEthics.to_string(),
363            "Integrity and Ethics"
364        );
365        assert_eq!(ControlScope::EntityLevel.to_string(), "Entity Level");
366        assert_eq!(CosoMaturityLevel::Defined.to_string(), "Defined");
367    }
368
369    #[test]
370    fn test_serde_roundtrip() {
371        let component = CosoComponent::ControlActivities;
372        let json = serde_json::to_string(&component).unwrap();
373        let deserialized: CosoComponent = serde_json::from_str(&json).unwrap();
374        assert_eq!(component, deserialized);
375
376        let principle = CosoPrinciple::FraudRisk;
377        let json = serde_json::to_string(&principle).unwrap();
378        let deserialized: CosoPrinciple = serde_json::from_str(&json).unwrap();
379        assert_eq!(principle, deserialized);
380    }
381}
datasynth_core/models/coso.rs

datasynth_core/models/
coso.rs
