cyntrisec 0.1.7__py3-none-any.whl

cyntrisec-0.1.7.dist-info/METADATA

@@ -0,0 +1,672 @@
+Metadata-Version: 2.4
+Name: cyntrisec
+Version: 0.1.7
+Summary: AWS capability graph analysis and attack path discovery CLI
+Author: CyntriSec
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           Copyright 2026 CyntriSec
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: attack-path,aws,cli,cost-optimization,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: pydantic>=2.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: moto>=5.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Cyntrisec CLI
+
+[![PyPI](https://img.shields.io/pypi/v/cyntrisec?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/cyntrisec/)
+[![Website](https://img.shields.io/badge/website-cyntrisec.com-4285F4?style=flat-square&logo=google-chrome&logoColor=white)](https://cyntrisec.com/)
+[![X](https://img.shields.io/badge/-%40cyntrisec-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/cyntrisec)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-orange?style=flat-square)](https://pypi.org/project/cyntrisec/)
+
+![image-download](https://github.com/user-attachments/assets/83a8b7d2-23c8-4e6e-a471-2e6a0a6f93e7)
+
+> [!CAUTION]
+> **Beta Software Disclaimer**: This tool is currently in **BETA**. It is provided "as is", without warranty of any kind.
+> While Cyntrisec is a read-only analysis tool by default, the user assumes all responsibility for any actions taken based on its findings.
+> **Always review** generated remediation plans and Terraform code before application.
+
+AWS capability graph analysis and attack path discovery.
+
+A read-only CLI tool that:
+- Scans AWS infrastructure via AssumeRole
+- Builds a capability graph (IAM, network, dependencies)
+- Discovers attack paths from internet to sensitive targets
+- Prioritizes fixes by ROI (security impact + cost savings)
+- Identifies unused capabilities (blast radius reduction)
+- Outputs deterministic JSON with proof chains
+
+## Architecture
+
+```text
++----------------------------------------------------------------------------------+
+|                                   CYNTRISEC CLI                                   |
++----------------------------------------------------------------------------------+
+| CLI Layer (Typer)                                                                 |
+|   scan   analyze   cuts   waste   report   comply   can   diff   serve   ...      |
++-----------------------------+----------------------------------------------------+
+| Core Engine                 | Storage (local)                                     |
+|  - AWS collectors           |  ~/.cyntrisec/scans/<scan_id>/                      |
+|  - Normalization/schema     |    snapshot.json, assets.json, relationships.json   |
+|  - GraphBuilder -> AwsGraph |    findings.json, attack_paths.json                 |
+|  - Path search -> paths     |  ~/.cyntrisec/scans/latest -> <scan_id>             |
+|  - Min-cut + Cost (ROI)     |  (Windows fallback: latest is a file)               |
++-----------------------------+----------------------------------------------------+
+| Outputs: JSON/agent, HTML report, remediation plan + Terraform hints              |
++----------------------------------------------------------------------------------+
+```
+
+<!-- Legacy Unicode diagram (kept for reference; may render oddly in some environments) -->
+<!--
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              CYNTRISEC CLI                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                         CLI Layer (typer)                           │    │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │    │
+│  │  │  scan   │ │ analyze │ │  cuts   │ │  waste  │ │ report  │ ...    │    │
+│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘        │    │
+│  └───────┼──────────┼──────────┼──────────┼──────────┼─────────────────┘    │
+│          │          │          │          │          │                      │
+│  ┌───────▼──────────▼──────────▼──────────▼──────────▼────────────────┐     │
+│  │                         Core Engine                                │     │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │     │
+│  │  │    Graph     │  │    Paths     │  │  Compliance  │              │     │
+│  │  │  (AwsGraph)  │  │  (BFS/DFS)   │  │  (CIS/SOC2)  │              │     │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘              │     │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │     │
+│  │  │    Cuts      │  │    Waste     │  │  Simulator   │              │     │
+│  │  │  (ROI/Min)   │  │  (Unused)    │  │  (IAM Eval)  │              │     │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘              │     │
+│  │  ┌──────────────┐                                                  │     │
+│  │  │ Cost Engine  │                                                  │     │
+│  │  │ (Estimator)  │                                                  │     │
+│  │  └──────────────┘                                                  │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│          │                                                                  │
+│  ┌───────▼────────────────────────────────────────────────────────────┐     │
+│  │                         AWS Layer                                  │     │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │     │
+│  │  │  Collectors  │  │  Normalizers │  │ Relationship │              │     │
+│  │  │  (EC2, IAM,  │  │  (Asset →    │  │   Builder    │              │     │
+│  │  │   RDS, ...)  │  │   Schema)    │  │              │              │     │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘              │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│          │                                          │                       │
+│  ┌───────▼──────────────────────┐   ┌──────────────▼──────────────────┐     │
+│  │      Storage Layer           │   │         MCP Server              │     │
+│  │  ┌────────────┐ ┌─────────┐  │   │  ┌──────────────────────────┐   │     │
+│  │  │ Filesystem │ │ Memory  │  │   │  │  Tools: get_scan_summary │   │     │
+│  │  │ (~/.cyntri │ │ (tests) │  │   │  │  get_attack_paths, ...   │   │     │
+│  │  │   sec/)    │ │         │  │   │  └──────────────────────────┘   │     │
+│  │  └────────────┘ └─────────┘  │   │                                 │     │
+│  └──────────────────────────────┘   └─────────────────────────────────┘     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            AWS Account                                      │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │     IAM     │  │     EC2     │  │     RDS     │  │     S3      │  ...    │
+│  │  (Roles,    │  │ (Instances, │  │ (Databases) │  │  (Buckets)  │         │
+│  │  Policies)  │  │  SGs, VPCs) │  │             │  │             │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+-->
+
+### Data Flow
+
+```text
+CLI (scan) --AssumeRole--> AWS Session --Describe/Get/List--> AWS APIs (read-only)
+     |
+     v
+Collectors -> normalize -> Assets + Relationships -> AwsGraph
+                                                |
+                                                v
+                                   Attack path search (BFS/DFS)
+                                                |
+                                                v
+                                   Min-cut (remediation cuts)
+                                                |
+                                                v
+                                      Cost engine (ROI)
+
+Local artifacts: ~/.cyntrisec/scans/<scan_id>/*.json
+```
+
+<!-- Legacy Unicode diagram (kept for reference; may render oddly in some environments) -->
+<!--
+```
+┌──────────┐    AssumeRole     ┌──────────┐    Describe/Get/List     ┌─────────┐
+│   CLI    │ ─────────────────▶│   AWS    │ ◀─────────────────────▶│  APIs   │
+│  (scan)  │                   │  Session │                          │(read-only)
+└────┬─────┘                   └──────────┘                          └─────────┘
+     │
+     ▼
+┌──────────┐    normalize      ┌──────────┐    build edges    ┌──────────────┐
+│Collectors│ ─────────────────▶│  Assets  │ ─────────────────▶│Relationships│
+└──────────┘                   └──────────┘                   └──────┬───────┘
+                                                                     │
+     ┌───────────────────────────────────────────────────────────────┐
+     ▼
+┌──────────┐    BFS/DFS        ┌──────────┐    min-cut        ┌──────────────┐
+│ AwsGraph │ ─────────────────▶│  Attack  │ ─────────────────▶│ Remediation │
+│          │                   │  Paths   │                   │    Cuts      │
+└──────────┘                   └──────────┘                   └──▲───────────┘
+                                                                 │ (ROI)
+                                                          ┌──────┴───────┐
+                                                          │ Cost Engine  │
+                                                          └──────────────┘
+```
+-->
+
+## Installation
+
+```bash
+pip install cyntrisec
+```
+
+### Windows PATH Fix
+
+If you see "cyntrisec is not recognized", the Scripts folder isn't on PATH:
+
+```powershell
+# Option 1: Run with python -m
+python -m cyntrisec --help
+
+# Option 2: Add to PATH for current session
+$env:PATH += ";$env:APPDATA\Python\Python311\Scripts"
+```
+
+## Quick Start
+
+> **Prerequisite**: Ensure you have [AWS CLI](https://aws.amazon.com/cli/) installed and configured with credentials (e.g., `aws configure`) or environment variables set. `terraform` is required for the setup step.
+
+```bash
+# 1. Create the read-only IAM role in your account
+cyntrisec setup iam 123456789012 --output role.tf
+
+# 2. Apply the Terraform
+cd your-infra && terraform apply
+
+# 3. Run a scan
+cyntrisec scan --role-arn arn:aws:iam::123456789012:role/CyntrisecReadOnly
+
+# 4. View attack paths
+cyntrisec analyze paths --min-risk 0.5
+
+# 5. Find minimal fixes (prioritized by ROI)
+cyntrisec cuts --format json
+
+# 6. Generate HTML report
+cyntrisec report --output report.html
+```
+
+## Commands
+
+### Core Analysis
+
+| Command | Description |
+|---------|-------------|
+| `scan` | Scan AWS infrastructure |
+| `analyze paths` | View attack paths |
+| `analyze findings` | View security findings |
+| `analyze stats` | View scan statistics |
+| `analyze business` | Business entrypoint analysis |
+| `report` | Generate HTML/JSON report |
+
+### Setup & Validation
+
+| Command | Description |
+|---------|-------------|
+| `setup iam` | Generate IAM role Terraform |
+| `validate-role` | Validate IAM role permissions |
+
+### Remediation
+
+| Command | Description |
+|---------|-------------|
+| `cuts` | Find minimal fixes (Cost & ROI prioritized) |
+| `waste` | Find unused IAM permissions |
+| `remediate` | Generate or optionally apply Terraform plans (gated) |
+
+### Policy Testing
+
+| Command | Description |
+|---------|-------------|
+| `can` | Test "can X access Y?" |
+| `diff` | Compare scan snapshots |
+| `comply` | Check CIS AWS / SOC2 compliance |
+
+### Agentic Interface
+
+| Command | Description |
+|---------|-------------|
+| `manifest` | Output machine-readable capabilities |
+| `explain` | Natural language explanations |
+| `ask` | Query scans in plain English |
+| `serve` | Run as MCP server for AI agents |
+
+## MCP Server Mode
+
+Run Cyntrisec as an MCP server for AI agent integration:
+
+```bash
+# Install with MCP support
+pip install "cyntrisec[mcp]"
+```
+
+```bash
+cyntrisec serve              # Start stdio server
+cyntrisec serve --list-tools # List available tools
+```
+
+### MCP Tools (15)
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| **Discovery** | `list_tools` | List all available tools |
+| | `set_session_snapshot` | Set active snapshot for session |
+| | `get_scan_summary` | Get summary of latest AWS scan |
+| **Assets** | `get_assets` | Get assets with type/name filtering |
+| | `get_relationships` | Get relationships between assets |
+| | `get_findings` | Get security findings with severity filtering |
+| **Attack Paths** | `get_attack_paths` | Get attack paths with risk scores |
+| | `explain_path` | Detailed hop-by-hop path breakdown |
+| | `explain_finding` | Detailed finding explanation |
+| **Remediation** | `get_remediations` | Find optimal fixes for attack paths |
+| | `get_terraform_snippet` | Generate Terraform code for remediation |
+| **Access** | `check_access` | Test if principal can access resource |
+| | `get_unused_permissions` | Find unused IAM permissions |
+| **Compliance** | `check_compliance` | Check CIS AWS or SOC 2 compliance |
+| | `compare_scans` | Compare scan snapshots |
+
+### Claude Desktop
+
+**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "cyntrisec": {
+      "command": "python",
+      "args": ["-m", "cyntrisec", "serve"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Run the following command to configure the server:
+
+```bash
+claude mcp add cyntrisec -- python -m cyntrisec serve
+```
+
+### Google Gemini / Antigravity
+
+Locate your agent configuration (e.g., `~/.gemini/antigravity/mcp_config.json`) and add:
+
+```json
+{
+  "mcpServers": {
+    "cyntrisec": {
+      "command": "python",
+      "args": ["-m", "cyntrisec", "serve"]
+    }
+  }
+}
+```
+
+## Trust & Safety
+
+### Read-Only Guarantees
+
+This tool makes **read-only API calls** to your AWS account. The IAM role
+should have only `Describe*`, `Get*`, `List*` permissions.
+
+### No Data Exfiltration
+
+All data stays on your local machine. Nothing is sent to external servers.
+Scan results are stored in `~/.cyntrisec/scans/`.
+
+### No Auto-Remediation (Default Safe Mode)
+
+By default, Cyntrisec is **read-only** and **does not modify** your AWS infrastructure.
+
+- It **analyzes** your account using read-only APIs.
+- It can **generate** remediation artifacts (e.g., Terraform modules) for you to review.
+- It does **not** apply changes automatically.
+
+### Optional Remediation Execution (Explicit Opt-In)
+
+Cyntrisec includes an **explicitly gated** path that can execute Terraform **only if you intentionally enable it**.
+
+This mode is:
+- **Disabled by default**
+- Requires `--enable-unsafe-write-mode`
+- Requires an additional explicit flag (e.g. `--execute-terraform`) to run Terraform
+- Intended for controlled environments (sandbox / CI with approvals), not unattended production
+
+If you do not pass these flags, Cyntrisec will never run `terraform apply`.
+
+### Write Operations
+
+Cyntrisec makes **no AWS write API calls** during scanning and analysis.
+
+The only supported "write" behavior is optional execution of Terraform **locally on your machine**, and only when explicitly enabled via unsafe flags.
+
+Every AWS API call is logged in CloudTrail under session name `cyntrisec-cli`.
+
+## Trust & Permissions
+
+Cyntrisec runs with a read-only IAM role. Generate the recommended policy with
+`cyntrisec setup iam <ACCOUNT_ID>` and keep permissions to `Describe*`, `Get*`,
+and `List*`. Live modes (`waste --live`, `can --live`) require extra IAM
+permissions; the generated policy and docs cover those additions.
+
+## Output Format
+
+Primary output is JSON to stdout. When stdout is not a TTY, the CLI automatically switches to JSON:
+
+```bash
+cyntrisec analyze paths --format json | jq '.paths[] | select(.risk_score > 0.7)'
+```
+
+Agent-friendly output wraps results in a structured envelope:
+
+```bash
+cyntrisec analyze paths --format agent
+```
+
+```json
+{
+  "schema_version": "1.0",
+  "status": "success",
+  "data": {...},
+  "artifact_paths": {...},
+  "suggested_actions": [...]
+}
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success / compliant |
+| 1 | Findings / regressions / denied |
+| 2 | Usage error |
+| 3 | Transient error (retry) |
+| 4 | Internal error |
+
+Use in CI/CD:
+
+```bash
+cyntrisec scan --role-arn $ROLE_ARN || exit 1
+cyntrisec diff || echo "Regressions detected"
+```
+
+## Storage
+
+Scan results are stored locally:
+
+```text
+~/.cyntrisec/
+|-- scans/
+|   |-- 2026-01-17_123456_123456789012/
+|   |   |-- snapshot.json
+|   |   |-- assets.json
+|   |   |-- relationships.json
+|   |   |-- findings.json
+|   |   `-- attack_paths.json
+|   `-- latest -> 2026-01-17_...
+`-- config.yaml
+```
+
+<!-- Legacy Unicode tree (kept for reference; may render oddly in some environments) -->
+<!--
+```
+~/.cyntrisec/
+├── scans/
+│   ├── 2026-01-17_123456_123456789012/
+│   │   ├── snapshot.json
+│   │   ├── assets.json
+│   │   ├── relationships.json
+│   │   ├── findings.json
+│   │   └── attack_paths.json
+│   └── latest -> 2026-01-17_...
+└── config.yaml
+```
+-->
+
+## Versioning
+
+This project follows Semantic Versioning. See `CHANGELOG.md` for release notes.
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [PyPI Package](https://pypi.org/project/cyntrisec/)
+- [Website](https://cyntrisec.com/)
+- [Twitter/X](https://x.com/cyntrisec)