[aws][fix] Add missing resource docs (#2227)

Author: aquamatthias

plugins/aws/fix_plugin_aws/collector.py

@@ -2,9 +2,7 @@
 from collections import defaultdict
 from concurrent.futures import Future, ThreadPoolExecutor
 from datetime import datetime, timedelta, timezone
-from typing import Any, Dict, List, Type, Optional, ClassVar, Union, cast, Dict, Any
-
-from attrs import define
+from typing import List, Type, Optional, Union, cast, Any
 
 from fix_plugin_aws.access_edges import AccessEdgeCreator
 from fix_plugin_aws.aws_client import AwsClient
@@ -51,8 +49,16 @@
     backup,
     bedrock,
 )
-from fix_plugin_aws.resource.base import AwsAccount, AwsApiSpec, AwsRegion, AwsResource, GraphBuilder
-from fixlib.baseresources import Cloud, EdgeType, BaseOrganizationalRoot, BaseOrganizationalUnit
+from fix_plugin_aws.resource.base import (
+    AwsAccount,
+    AwsApiSpec,
+    AwsRegion,
+    AwsResource,
+    GraphBuilder,
+    AwsOrganizationalRoot,
+    AwsOrganizationalUnit,
+)
+from fixlib.baseresources import Cloud, EdgeType
 from fixlib.core.actions import CoreFeedback, ErrorAccumulator
 from fixlib.core.progress import ProgressDone, ProgressTree
 from fixlib.graph import Graph, BySearchCriteria, ByNodeId
@@ -463,23 +469,3 @@ def add_accounts(parent: Union[AwsOrganizationalRoot, AwsOrganizationalUnit]) ->
                 create_org_graph()
             except Exception as e:
                 log.exception(f"Error creating organization graph: {e}")
-
-
-@define(eq=False, slots=False)
-class AwsOrganizationalRoot(BaseOrganizationalRoot, AwsResource):
-    kind: ClassVar[str] = "aws_organizational_root"
-    _kind_display: ClassVar[str] = "AWS Organizational Root"
-    _kind_description: ClassVar[str] = "AWS Organizational Root is the top-level entity in AWS Organizations. It serves as the starting point for creating and managing multiple AWS accounts within an organization. The root provides centralized control over billing, access management, and resource allocation across all member accounts, ensuring consistent policies and governance throughout the organizational structure."  # fmt: skip
-    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_root.html"
-    _kind_service = "organizations"
-    _metadata: ClassVar[Dict[str, Any]] = {"icon": "group", "group": "management"}
-
-
-@define(eq=False, slots=False)
-class AwsOrganizationalUnit(BaseOrganizationalUnit, AwsResource):
-    kind: ClassVar[str] = "aws_organizational_unit"
-    _kind_display: ClassVar[str] = "AWS Organizational Unit"
-    _kind_description: ClassVar[str] = "An AWS Organizational Unit is a container for AWS Accounts."
-    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_ous.html"
-    _kind_service = "organizations"
-    _metadata: ClassVar[Dict[str, Any]] = {"icon": "group", "group": "management"}

plugins/aws/fix_plugin_aws/resource/amazonq.py

@@ -48,10 +48,8 @@ def service_name(cls) -> str:
 class AwsQBusinessApplication(AmazonQTaggable, AwsResource):
     kind: ClassVar[str] = "aws_q_business_application"
     _kind_display: ClassVar[str] = "AWS Q Business Application"
-    _kind_description: ClassVar[str] = (
-        "Represents a Q Business application within the AWS Q Business service. Applications"
-        " define a set of tasks and configuration for processing data within the Q Business ecosystem."
-    )
+    _kind_description: ClassVar[str] = "An AWS Q Business Application is a specialized AI assistant tailored for specific business functions or roles. It integrates with an organization's data sources and systems to provide contextual responses and perform tasks within a particular domain. Q Business Applications support users in accessing information, solving problems, and completing work activities relevant to their operational area."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-app.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "application", "group": "ai"}
     _aws_metadata: ClassVar[Dict[str, Any]] = {
@@ -314,10 +312,8 @@ def collect_index_resources(
 class AwsQBusinessConversation(AwsResource):
     kind: ClassVar[str] = "aws_q_business_conversation"
     _kind_display: ClassVar[str] = "AWS Q Business Conversation"
-    _kind_description: ClassVar[str] = (
-        "Represents a conversation within the AWS Q Business service. Conversations are"
-        " interactions that involve a series of messages or data exchanges."
-    )
+    _kind_description: ClassVar[str] = "An AWS Q Business Conversation is an interaction between a user and an AWS Q Business Application. It involves a series of exchanges where the user asks questions, requests information, or issues commands, and the AI assistant responds with relevant answers, performs tasks, or provides guidance. These conversations are context-aware and draw upon the organization's connected data sources and systems."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Conversation.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "resource", "group": "ai"}
     # Collected via AwsQBusinessApplication()
@@ -348,10 +344,8 @@ def service_name(cls) -> str:
 class AwsQBusinessDataSource(AmazonQTaggable, AwsResource):
     kind: ClassVar[str] = "aws_q_business_data_source"
     _kind_display: ClassVar[str] = "AWS Q Business Data Source"
-    _kind_description: ClassVar[str] = (
-        "Represents a data source in the AWS Q Business service. Data sources are the origins"
-        " from which data is ingested for processing or analysis within the Q Business framework."
-    )
+    _kind_description: ClassVar[str] = "An AWS Q Business Data Source is a repository of information connected to AWS Q Business Applications. It includes various types of business data, such as documents, databases, or APIs, that the AI assistant accesses to provide accurate and contextual responses. These data sources form the knowledge base that Q Business Applications use to answer queries and perform tasks within specific business domains."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-sources.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "bucket", "group": "ai"}
     # Collected via AwsQBusinessApplication()
@@ -438,9 +432,9 @@ class AwsQBusinessDataSourceSyncJobMetrics:
 class AwsQBusinessDataSourceSyncJob(AwsResource):
     kind: ClassVar[str] = "aws_q_business_data_source_sync_job"
     _kind_display: ClassVar[str] = "AWS Q Business Data Source Sync Job"
-    _kind_description: ClassVar[str] = (
-        "Represents a data source synchronization job in the AWS Q Business service. Sync jobs"
-        " ensure that data from data sources is up-to-date and correctly integrated into the system."
+    _kind_description: ClassVar[str] = "An AWS Q Business Data Source Sync Job is a process that updates and synchronizes data between external sources and AWS Q Business Applications. It retrieves new or modified information from connected data repositories, processes it, and integrates it into the AI assistant's knowledge base. This job ensures that Q Business Applications have access to the most current and relevant data for responding to user queries."  # fmt: skip
+    _docs_url: ClassVar[str] = (
+        "https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StartDataSourceSyncJob.html"
     )
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "job", "group": "ai"}
@@ -518,10 +512,7 @@ def service_name(cls) -> str:
 class AwsQBusinessIndice(AmazonQTaggable, AwsResource):
     kind: ClassVar[str] = "aws_q_business_indice"
     _kind_display: ClassVar[str] = "AWS Q Business Indice"
-    _kind_description: ClassVar[str] = (
-        "Represents an index in the AWS Q Business service. Indices are used to organize and"
-        " facilitate efficient searching and retrieval of data within the Q Business framework."
-    )
+    _kind_description: ClassVar[str] = "An AWS Q Business Indice is a structured collection of data used by AWS Q Business Applications. It organizes and indexes information from various data sources, optimizing it for quick retrieval and analysis. This indice supports efficient searching, filtering, and querying of business data, enhancing the AI assistant's ability to provide accurate and timely responses to user inquiries within specific business contexts."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/qs/latest/userguide/business-indices-qs.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "config", "group": "ai"}
@@ -806,7 +797,7 @@ def delete_resource(self, client: AwsClient, graph: Graph) -> bool:
 class AwsQBusinessRetriever(AmazonQTaggable, AwsResource):
     kind: ClassVar[str] = "aws_q_business_retriever"
     _kind_display: ClassVar[str] = "AWS Q Business Retriever"
-    _kind_description: ClassVar[str] = ""  # fmt: skip
+    _kind_description: ClassVar[str] = "AWS Q Business Retriever is a machine learning model for information retrieval in enterprise settings. It processes and indexes business data from various sources, then responds to user queries with relevant information and documents. The model understands context and intent, providing accurate search results and summaries to help users find and utilize business information efficiently."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/bedrock/latest/userguide/retriever.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "application", "group": "ai"}
@@ -927,10 +918,8 @@ class AwsQAppsCategory:
 class AwsQAppsLibraryItem(AwsResource):
     kind: ClassVar[str] = "aws_q_apps_library_item"
     _kind_display: ClassVar[str] = "AWS QApps Library Item"
-    _kind_description: ClassVar[str] = (
-        "Represents a library item in the AWS QApps service. Library items include resources"
-        " such as scripts, templates, or other components that can be used in QApps applications."
-    )
+    _kind_description: ClassVar[str] = "An AWS Q Apps Library Item is a component within the AWS Q Apps ecosystem that represents a specific resource or functionality. It can be a pre-built template, module, or configuration element used to construct or enhance Q Apps. These items are stored in a centralized library, facilitating reuse and standardization across different Q Apps within an organization."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_GetLibraryItem.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "image", "group": "ai"}
     # Collected via AwsQBusinessApplication()
@@ -1008,10 +997,8 @@ def service_name(cls) -> str:
 class AwsQApps(AwsResource):
     kind: ClassVar[str] = "aws_q_apps"
     _kind_display: ClassVar[str] = "AWS QApps"
-    _kind_description: ClassVar[str] = (
-        "Represents an application within the AWS QApps service. QApps applications include"
-        " various components and configurations for developing and deploying apps within the AWS environment."
-    )
+    _kind_description: ClassVar[str] = "AWS Q Apps are purpose-built AI assistants tailored for specific business functions or roles. They integrate with an organization's data and systems to provide contextual responses and perform tasks. Q Apps offer personalized support for various domains such as IT, finance, and sales, helping users access information, solve problems, and complete work-related activities within their operational context."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/amazonq/"
     _kind_service: ClassVar[Optional[str]] = service_name
     _metadata: ClassVar[Dict[str, Any]] = {"icon": "application", "group": "ai"}
     # Collected via AwsQBusinessApplication()

plugins/aws/fix_plugin_aws/resource/base.py

@@ -29,6 +29,8 @@
     EdgeType,
     ModelReference,
     PhantomBaseResource,
+    BaseOrganizationalRoot,
+    BaseOrganizationalUnit,
 )
 from fixlib.config import Config, current_config
 from fixlib.core.actions import CoreFeedback, SuppressWithFeedback
@@ -119,7 +121,9 @@ class AwsResource(BaseResource, ABC):
     # The display name of the kind.
     _kind_display: ClassVar[str] = "AWS Resource"
     # The description of the kind.
-    _kind_description: ClassVar[str] = "AWS Resource is a generic term used to refer to any type of resource available in Amazon Web Services cloud."  # fmt: skip
+    _kind_description: ClassVar[str] = "An AWS Resource is a component within Amazon Web Services (AWS) that represents a specific entity or service in the cloud. It can be an instance, database, storage bucket, network interface, or other element. AWS Resources are created, managed, and monitored through the AWS Management Console, APIs, or command-line tools."  # fmt: skip
+    # The URL to the documentation of this kind.
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/"
     # AWS specific metadata that hold template strings for ARN and provider link.
     _aws_metadata: ClassVar[Dict[str, Any]] = {}
     # The mapping to transform the incoming API json into the internal representation.
@@ -315,11 +319,7 @@ class AwsAccount(BaseAccount, AwsResource, BaseIamPrincipal):
 class AwsRegion(BaseRegion, AwsResource):
     kind: ClassVar[str] = "aws_region"
     _kind_display: ClassVar[str] = "AWS Region"
-    _kind_description: ClassVar[str] = (
-        "An AWS Region is a physical location where AWS has multiple data centers,"
-        " allowing users to choose the geographic area in which their resources are"
-        " located."
-    )
+    _kind_description: ClassVar[str] = "An AWS Region is a geographic area containing multiple data centers called Availability Zones. It provides a distinct set of AWS services and infrastructure. Regions are isolated from each other, enhancing fault tolerance and stability. Users can deploy resources in different Regions to reduce latency and meet data residency requirements."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/general/latest/gr/rande.html"
     _reference_kinds: ClassVar[ModelReference] = {
         "successors": {
@@ -417,6 +417,26 @@ class AwsEc2VolumeType(AwsResource, BaseVolumeType):
     _aws_metadata: ClassVar[Dict[str, Any]] = {"provider_link_tpl": None, "arn_tpl": "arn:{partition}:ec2:{region}:{account}:volume/{id}"}  # fmt: skip
 
 
+@define(eq=False, slots=False)
+class AwsOrganizationalRoot(BaseOrganizationalRoot, AwsResource):
+    kind: ClassVar[str] = "aws_organizational_root"
+    _kind_display: ClassVar[str] = "AWS Organizational Root"
+    _kind_description: ClassVar[str] = "AWS Organizational Root is the top-level entity in AWS Organizations. It serves as the starting point for creating and managing multiple AWS accounts within an organization. The root provides centralized control over billing, access management, and resource allocation across all member accounts, ensuring consistent policies and governance throughout the organizational structure."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_root.html"
+    _kind_service = "organizations"
+    _metadata: ClassVar[Dict[str, Any]] = {"icon": "group", "group": "management"}
+
+
+@define(eq=False, slots=False)
+class AwsOrganizationalUnit(BaseOrganizationalUnit, AwsResource):
+    kind: ClassVar[str] = "aws_organizational_unit"
+    _kind_display: ClassVar[str] = "AWS Organizational Unit"
+    _kind_description: ClassVar[str] = "AWS Organizational Unit is a container for AWS accounts within an organization. It groups accounts for management purposes and applies policies across multiple accounts. Organizational Units can be nested to create hierarchies, facilitating centralized control over permissions, compliance, and resource access. This structure supports governance and organizational alignment in complex AWS environments."  # fmt: skip
+    _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_ous.html"
+    _kind_service = "organizations"
+    _metadata: ClassVar[Dict[str, Any]] = {"icon": "group", "group": "management"}
+
+
 class GraphBuilder:
     def __init__(
         self,

plugins/aws/fix_plugin_aws/resource/iam.py

@@ -219,7 +219,7 @@ class AwsIamServerCertificate(AwsResource, BaseCertificate):
     kind: ClassVar[str] = "aws_iam_server_certificate"
     _kind_display: ClassVar[str] = "AWS IAM Server Certificate"
     _aws_metadata: ClassVar[Dict[str, Any]] = {"arn_tpl": "arn:{partition}:iam:{region}:{account}:server-certificate/{name}"}  # fmt: skip
-    _kind_description: ClassVar[str] = ""  # fmt: skip
+    _kind_description: ClassVar[str] = "AWS IAM Server Certificate is a digital credential used to secure network communications for AWS services and applications. It authenticates the identity of servers and encrypts data transmitted between clients and servers. IAM Server Certificates can be managed, rotated, and deployed across multiple AWS regions to establish secure HTTPS connections for websites and applications."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_server-certs.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     api_spec: ClassVar[AwsApiSpec] = AwsApiSpec(
@@ -618,10 +618,7 @@ class AwsRootUser(AwsResource, BaseUser, BaseIamPrincipal):
     kind: ClassVar[str] = "aws_root_user"
     _kind_display: ClassVar[str] = "AWS Root User"
     _aws_metadata: ClassVar[Dict[str, Any]] = {"arn_tpl": "arn:{partition}:None:{region}:{account}:resource/{id}"}  # fmt: skip
-    _kind_description: ClassVar[str] = (
-        "The AWS Root User is the initial user created when setting up an AWS account"
-        " and has unrestricted access to all resources in the account."
-    )
+    _kind_description: ClassVar[str] = "The AWS Root User is the primary account holder for an Amazon Web Services (AWS) account. It has full access to all AWS services and resources within the account. The Root User can create and manage other users, assign permissions, and make billing changes. It should be used sparingly for security reasons."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     _reference_kinds: ClassVar[ModelReference] = {
@@ -640,7 +637,7 @@ class AwsIamUser(AwsResource, BaseUser, BaseIamPrincipal):
     kind: ClassVar[str] = "aws_iam_user"
     _kind_display: ClassVar[str] = "AWS IAM User"
     _aws_metadata: ClassVar[Dict[str, Any]] = {"provider_link_tpl": "https://{region_id}.console.aws.amazon.com/iam/home?region={region}#/users/details/{name}", "arn_tpl": "arn:{partition}:iam::{account}:user/{name}"}  # fmt: skip
-    _kind_description: ClassVar[str] = ""  # fmt: skip
+    _kind_description: ClassVar[str] = "AWS IAM User is an identity within Amazon Web Services that represents a person or application. It has associated credentials and permissions that determine its access to AWS services and resources. IAM Users can be assigned to groups, given specific policies, and authenticated using passwords or access keys for programmatic access to AWS."  # fmt: skip
     _docs_url: ClassVar[str] = "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html"
     _kind_service: ClassVar[Optional[str]] = service_name
     api_spec: ClassVar[AwsApiSpec] = AwsApiSpec(service_name, "get-account-authorization-details")