{"id":438,"date":"2025-07-12T15:49:15","date_gmt":"2025-07-12T15:49:15","guid":{"rendered":"https:\/\/blog.lottabytes.com\/?p=438"},"modified":"2025-07-12T15:49:15","modified_gmt":"2025-07-12T15:49:15","slug":"describing-systems-architecture-documentation","status":"publish","type":"post","link":"https:\/\/blog.lottabytes.com\/index.php\/2025\/07\/12\/describing-systems-architecture-documentation\/","title":{"rendered":"Describing Systems – Architecture Documentation"},"content":{"rendered":"\n

Note: This article is a copy of one I have written for the compliance.engineering<\/a> site.<\/em> Check it out!<\/p>\n\n\n\n

The organizational dilemma of understanding systems<\/h3>\n\n\n\n

Every day decisions are made, from the low-risk decision on how you would like your coffee or tea, to high-risk decisions on organizational strategy or accepting the implications stemming from proposed contractual terms with a customer or partner.\u00a0 These decisions all require related, supporting information and success in making the correct decisions requires a prerequisite level of accuracy and exposure to the proper information in a holistic snapshot.\u00a0 Without that proper exposure to relevant details, as well as an accurate understanding of what those details mean, the consequence can negatively impact your business in a significant way.<\/p>\n\n\n\n

Organizational management of IT systems and underlying processes is no different, its severity just sits on the mid-to-upper end of risk management for the large organization.\u00a0 With contractual commitments, as well as regulatory requirements (e.g., SOX<\/a>, PCI<\/a>, FedRAMP<\/a>, etc.) it is critical that the organizational leadership is well and accurately informed of the state of their digital estate.\u00a0 With the involvement of external auditors, the risk of accidental discovery of previously-undiscovered deficiencies goes up.\u00a0 Because of this, it\u2019s critical that the organization has a clear, accurate, and concise understanding of all their systems.\u00a0 Without this understanding the organization runs the undue risk of damages via accidental data leakage, data loss via intrusion, accidental outage, or exposure and audit failure due to external findings.<\/p>\n\n\n\n

The current landscape<\/h3>\n\n\n\n

So, how do organizations manage these systems?\u00a0 The answer isn\u2019t ideal, as the approaches are quite fragmented and vary (often in materially significant ways) between organizations.\u00a0 A smaller organizational entity might have a solid understanding of its digital estate and configurations, while a much larger enterprise might have significant technical debt and loss of understanding assets due to years of team turnover.\u00a0 The more mature organizations will often have a process for reviewing operational systems and processes.\u00a0 These organizations will also often have a production readiness assessment workflow, along with ongoing review to ensure compliance with appropriate business standards, especially in the realm of security and privacy.\u00a0 However, even in these, currently-ideal scenarios, the methods of discovery, documentation, presentation of details, and sharing of maturity scores and findings is highly varied – both in effectiveness as well as in interoperability between teams and corporate entities.\u00a0 Often though, these assessment processes exist, but don\u2019t operate in a meaningfully effective way.\u00a0 In this worst case scenario it can provide a sense of false confidence in the associated resilience, security, and associated risk of an organization\u2019s systems.<\/p>\n\n\n\n

Without a solid grasp of a system\u2019s architecture and design, implementation details, operational practices, and risk mitigation strategies, an organization is left with a significant gap in truly understanding their security posture and appropriately managing the associated risk.\u00a0 A breakdown of foundational knowledge of your system can start small, such as a lapse in proper patching of nodes based on your business practices and associated commitments.\u00a0 That issue compounds when, due to a lack of accurate knowledge, your internet-exposed footprint neglects to document that those nodes are exposed on the internet.\u00a0 This gap grows organically as now during your annual penetration testing those IPs\/FQDNs are not tested as they aren\u2019t realized to be in-scope of testing.\u00a0 This predictable scenario can eventually lead to a successful, malicious compromise of your systems, all stemming back to a fundamental lack of understanding the system\u2019s architecture, configuration, and associated security details.<\/p>\n\n\n\n

Ignoring the possibility of a security breach that leads to possible loss of data (and associated trust), the risks also exist on the corporate side.  With the declarations made during various compliance endeavors, as well as those enshrined in corporate contracts, there is risk that what is expected varies from the actual state of an organization\u2019s systems.  As many audit reports will state, their assessment is based solely on the information provided by the organization being assessed, and if that information is found to be lacking, then risk of litigation arises against the organization.  Even before that though, the risk of being questioned by an auditor on your controls can lead them to potentially uncover aspects of the system that were previously overlooked by the organization.  While less damaging, this scenario is still an embarrassment and can lead to a qualified opinion or audit failure, with the associated corporate fallout once the findings are released.<\/p>\n\n\n\n

Discovery, Documentation, and Dissemination <\/h3>\n\n\n\n

So, what can we do to improve this position, not just at one organization, but at a national or global level?  The answer to that question is likely multi-dimensional, but I believe is one that hinges on several key actions.  First, we must be serious about defining the scope of our systems and realize that it\u2019s likely larger than we\u2019d like to admit based on underlying dependencies.  Second, we must have a consistent approach to defining what makes up a system. Third, we need to have a consistent method to gather information about the system and store it in a machine-readable format that can be shared and consumed by other parties.  Lastly, we must move to enabling development, operational changes, and breakfix with automated methods to ensure that changes made aren\u2019t going to compromise the desired state of our systems.  Let\u2019s look into each of these in more detail.<\/p>\n\n\n\n

Scope is important, even critical in determining if we have cast a wide-enough net around what we are trying to define, describe, and ultimately protect.\u00a0 The challenge here is that there are so many ways to describe a system, from code used, to physical or virtual machines, cloud accounts, etc.; that the challenge becomes describing what the difference is between a portfolio, a product, a component, and even a feature – not to mention supporting infrastructure and services.\u00a0 To compound this issue, organizations have an internal drive to reduce the inspected\/managed scope to be as small as possible for audit purposes, as that reduction in scope increases the chance of success during audit.\u00a0 While this is its own subject that could consume hours of discussion, I believe that the fundamental, defining factor of a system is connectivity<\/strong><\/a>, and as such all scoping should use connectivity as the definitive building block in description and scoping.\u00a0 To make this happen in my previous role we started by defining all ports and protocols across all the components of the system being assessed.\u00a0 Using this information, architecture diagrams were automatically generated<\/span>, thus ensuring that our diagrams matched with the reality of what was really at play.\u00a0 Almost without fail this step eliminated over-simplification of the system, as well as allowing us to easily identify components that would otherwise be overlooked, or not mentioned by the owning team.<\/p>\n\n\n\n

Systems are often more than one or more related devices, so as such the second principle we need is to ensure that our understanding of the system covers all the applicable systems, including supporting ones.\u00a0 To use an example, you may have a production web service that stores customer data.\u00a0 However, as part of that system you also need to consider everything from the workstations with access for managing that web application, to the CI\/CD pipeline managing the deployment, to the supporting security tools such as your SIEM and NIDS devices, even the backup site where you store copies of that sensitive data.\u00a0 Without a proper understanding of the entire ecosystem an organization quickly falls prey to issues such as the logging agents being installed, but the SIEM not actually receiving or parsing the logs.\u00a0 Or, perhaps an internet gateway owned by another team is providing access to your system, but it\u2019s not being managed by your internal security processes and slips through the cracks.\u00a0 Whatever the negative scenario, every system needs to be measured holistically, and not necessarily just the device(s) that most of us would jump to classify as \u201cthe system\u201d.<\/p>\n\n\n\n

While many organizations have successfully implemented either a holistic or partial strategy for these first two fundamentals, very few are even starting to plan on how to implement their process in a way that is machine-readable and suitable for re-use across teams and enterprises.\u00a0 This is a new, emerging trend as cybersecurity is beginning to mature to a layered understanding, where each system is understood to be reliant on underlying systems.\u00a0 Much like a Software Bill of Materials (SBOM)<\/a> is used to show all the varied layers of what code makes up a system, or the Vulnerability Exploitability Exchange (VEX)<\/a> shows exploitability of those components in a standardized way, so too do we need the ability to have a consistent, additive (per layer) way to measure the security and compliance aspects of the holistic system with all its layers being accounted for.\u00a0 If your enterprise\u2019s own internally-developed code is compliant, but uses an underlying library or database that isn\u2019t, then your current state is only at the level of those underlying and deficient dependencies.\u00a0 Today, there isn\u2019t a commonly used way to have this additive analysis of components that span proprietary and open source code in a meaningful way, especially when it comes to compliance. \u00a0 When this point is reached, then we can truly start to realize a future of compliance as code.\u00a0\u00a0<\/p>\n\n\n\n

Future Plans<\/h3>\n\n\n\n

This future, where a developer\u2019s commit is rejected with an automated trigger and explanation that the functionality in that commit breaks certain security or compliance-related requirements that first need to be resolved, is ideal; as far left in the process as possible.\u00a0 This same future where compliance can programmatically be described in a standardized syntax (e.g., OSCAL<\/a>) with consistent policy language, where organizations begin realizing the currently-sought-after value being missed in countless security and privacy questionnaires, reviews, and interviews.\u00a0 To get to this future, we must become consistent in our scoping, description, and documentation of services in a universal manner.\u00a0 This is the first of ten articles that are intended to extrapolate the needs, route, and tools to make the journey to universally-usable service details available across organizations, as well as through the various layers of proprietary and open source solutions and bring us towards achieving this vision.<\/p>\n","protected":false},"excerpt":{"rendered":"

Note: This article is a copy of one I have written for the compliance.engineering site. Check it out! The organizational dilemma of understanding systems Every day decisions are made, from the low-risk decision on how you would like your coffee or tea, to high-risk decisions on organizational strategy or accepting the implications stemming from proposed … <\/p>\n

Read more “Describing Systems – Architecture Documentation”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[117,113,119,116,120,115,121,53,114,118],"class_list":["post-438","post","type-post","status-publish","format-standard","hentry","category-uncategorized","tag-architecture","tag-compliance","tag-documentation","tag-fedramp","tag-oscal","tag-pci","tag-risk-management","tag-security","tag-sox","tag-systems"],"_links":{"self":[{"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/posts\/438","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/comments?post=438"}],"version-history":[{"count":1,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/posts\/438\/revisions"}],"predecessor-version":[{"id":439,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/posts\/438\/revisions\/439"}],"wp:attachment":[{"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/media?parent=438"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/categories?post=438"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.lottabytes.com\/index.php\/wp-json\/wp\/v2\/tags?post=438"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}