mallcop 0.1.0__tar.gz

mallcop-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+                                 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 the 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 the 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 any 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 Mallcop Contributors
+
+   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.

mallcop-0.1.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: mallcop
+Version: 0.1.0
+Summary: Security monitoring for small cloud operators
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: regex>=2024.0
+Requires-Dist: requests>=2.28
+Provides-Extra: aws
+Requires-Dist: boto3>=1.28; extra == "aws"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# mallcop
+
+Security monitoring for small cloud operators. AI-native. Self-hosted. Near-$0.
+
+## What is this?
+
+Mallcop watches your cloud infrastructure and tells you when something's wrong. It's designed for AI agents to operate -- not humans clicking dashboards.
+
+Think of it as the security guard at your mall. Not a SWAT team. Just someone who knows the building, notices when something's off, and calls you when it matters.
+
+## Who is it for?
+
+- Solo founders running cloud services
+- Small teams too small for a SIEM, too exposed for nothing
+- AI agents operating infrastructure that need security awareness
+
+## What does it monitor?
+
+8 connectors, 12 detectors, 9 domain skills, 6 actors, 56 Academy Exam scenarios. 2664 tests.
+
+### Connectors
+
+| Connector | What it watches |
+|-----------|----------------|
+| **Azure** | Activity log, container apps, resource modifications, Defender alerts |
+| **AWS CloudTrail** | IAM changes, security group modifications, console logins, S3 policy changes |
+| **GitHub** | Repo changes, permission changes, security alerts, Actions |
+| **Microsoft 365** | Sign-ins, admin actions, email events |
+| **Vercel** | Deployments, audit log, team membership changes |
+| **Container Logs** | Container app stdout/stderr via Log Analytics |
+| **Supabase** | Auth audit logs, Management API config monitoring |
+| **OpenClaw** | Skill integrity, config drift, gateway security (via ClawCop) |
+
+### Detectors
+
+| Detector | What it catches |
+|----------|----------------|
+| **priv-escalation** | Role grants, permission changes, self-elevation |
+| **unusual-timing** | Activity outside established patterns |
+| **auth-failure-burst** | Brute force and credential stuffing |
+| **volume-anomaly** | Unusual event volume spikes |
+| **new-actor** | Previously unseen identities |
+| **new-external-access** | External access from new sources |
+| **unusual-resource-access** | Known actors touching new resources |
+| **injection-probe** | Prompt injection attempts in event data |
+| **log-format-drift** | Container log format changes (parser degradation) |
+| **git-oops** | Leaked credentials in git repos |
+| **malicious-skill** | Encoded payloads, quarantine bypass, known-bad authors in OpenClaw skills |
+| **openclaw-config-drift** | Auth disabled, plaintext secrets, mDNS broadcasting |
+
+### Domain Skills
+
+9 SSH-signed investigation skills with a PKI trust web. Skills provide domain-specific reasoning that investigation actors load on demand.
+
+| Skill | Domain |
+|-------|--------|
+| **privilege-analysis** | General privilege escalation reasoning (parent skill) |
+| **aws-iam** | IAM trust policies, AssumeRole chains, SCPs |
+| **azure-security** | Azure RBAC, Activity Log, Container Apps, Defender |
+| **github-security** | Repository permissions, Actions, deploy keys |
+| **supabase-security** | Auth policies, RLS, Management API |
+| **container-logs-security** | Log analysis, crash patterns, log injection |
+| **openclaw-security** | Malicious skill detection, ClawHavoc IOCs |
+| **m365-security** | Sign-in analysis, admin operations |
+| **vercel-security** | Deployment security, team access |
+
+Skills are signed with SSH keys and verified against a trust web (anchors, endorsements, BFS trust chain). `skills.lock` pins content hashes. Unsigned or tampered skills are refused.
+
+### Actors
+
+| Actor | Role |
+|-------|------|
+| **triage** | Level-1: quick severity assessment, resolve or escalate |
+| **investigate** | Level-2: deep investigation with tools, skills, and baseline cross-reference |
+| **heal** | Auto-remediation for parser drift and config issues |
+| **notify-teams** | Microsoft Teams webhook notifications |
+| **notify-slack** | Slack Block Kit notifications |
+| **notify-email** | HTML digest email via SMTP |
+
+### ClawCop — OpenClaw Security Monitor
+
+Mallcop watches your cloud. ClawCop watches your AI agent.
+
+ClawCop is mallcop's built-in OpenClaw security capability. Add the `openclaw` connector to your `mallcop.yaml` and it works through the standard scan/detect/escalate pipeline.
+
+It catches malicious skills, config drift, and skill lifecycle changes. No API credentials required -- reads directly from `~/.openclaw/`. See [docs/clawcop.md](docs/clawcop.md) for details.
+
+### Academy Exam
+
+56 adversarial scenarios that test mallcop's investigation quality. Each scenario presents a security finding with a trap -- a deceptive element designed to exploit common reasoning failures (admin exemption, known-actor bias, context switching).
+
+```bash
+mallcop exam run                    # run all scenarios
+mallcop exam run --tag AE           # run admin-exemption scenarios only
+mallcop exam run --scenario PE-01   # run one specific scenario
+mallcop improve --from-exam results.json  # analyze failures, suggest fixes
+```
+
+Graded by an LLM judge on reasoning quality, investigation thoroughness, and actionability. Not pass/fail on the action -- pass/fail on whether the investigation was rigorous.
+
+### Entity Reputation
+
+Tracks per-entity trust scores across all connectors. Findings decrement scores by severity. Baseline matches reward scores. Scores decay toward neutral with a 30-day half-life.
+
+## Install
+
+```bash
+pip install mallcop
+```
+
+## Quickstart
+
+### 1. Initialize
+
+```bash
+mkdir my-security && cd my-security
+git init
+mallcop init
+```
+
+`mallcop init` discovers your environment -- probes for Azure subscriptions, GitHub orgs, and other connected platforms. It writes a `mallcop.yaml` config file and reports estimated costs.
+
+All output is JSON by default (for AI agents). Use `--human` for readable output on any command.
+
+### 2. First scan
+
+```bash
+mallcop scan
+mallcop detect
+```
+
+`mallcop scan` polls all configured connectors and stores events in `events/` as JSONL files.
+
+`mallcop detect` runs detectors against stored events and writes findings to `findings.jsonl`.
+
+During the first 14 days (the baseline learning period), detectors log findings as informational only -- no escalation, no alerts. This lets mallcop learn what "normal" looks like for your environment.
+
+### 3. Automated monitoring
+
+```bash
+mallcop watch              # scan + detect + escalate
+mallcop watch --dry-run    # skip actor escalation
+```
+
+### 4. Set up scheduled runs
+
+The recommended setup is a GitHub Actions workflow that runs every 6 hours:
+
+```yaml
+name: mallcop-watch
+on:
+  schedule:
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+
+jobs:
+  watch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install mallcop
+      - run: mallcop watch
+        env:
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+      - run: |
+          git config user.name "mallcop"
+          git config user.email "mallcop@noreply"
+          git add -A
+          git diff --cached --quiet || git commit -m "mallcop watch $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          git push
+```
+
+### 5. Investigation
+
+```bash
+mallcop review                      # orient: all open findings + context
+mallcop investigate <finding-id>    # deep investigation with tools + skills
+mallcop events --finding <id>       # query events
+mallcop baseline --actor <actor>    # check baseline for an actor
+mallcop report --status open --severity warn,critical
+```
+
+### 6. Skill and trust management
+
+```bash
+mallcop skill list                  # show installed skills
+mallcop skill sign <dir> --key <keyfile>   # sign a skill directory
+mallcop skill verify <dir>          # verify skill signature
+mallcop skill lock                  # regenerate skills.lock
+mallcop trust add-anchor <id> <pubkey>     # add trust anchor
+mallcop trust endorse <id> --scope "aws-*" --level author --key <keyfile>
+mallcop trust chain <identity>      # show trust path
+mallcop trust list                  # show trust web
+```
+
+## CLI commands
+
+```
+# Core pipeline
+mallcop init                        # discover environment, write config
+mallcop scan                        # poll all connectors, store events
+mallcop detect                      # run detectors against events
+mallcop escalate                    # invoke actor chain on open findings
+mallcop watch [--dry-run]           # scan + detect + escalate
+
+# Investigation
+mallcop review                      # POST.md + all open findings + commands
+mallcop investigate <finding-id>    # deep context for one finding
+mallcop finding <finding-id>        # finding detail + annotation trail
+mallcop events [--finding] [--actor] [--source] [--hours] [--type]
+mallcop report [--status] [--severity] [--since]
+mallcop baseline [--actor] [--entity]
+mallcop status [--costs]            # operational status and cost trends
+
+# Finding management
+mallcop annotate <finding-id> <text>
+mallcop ack <finding-id> [--reason]
+
+# Skills and trust
+mallcop skill list | sign | verify | lock
+mallcop trust add-anchor | add-key | endorse | chain | list
+
+# Quality
+mallcop exam run [--tag] [--scenario] [--model]
+mallcop improve [--from-exam <file>] [--refresh-patterns]
+
+# Development
+mallcop scaffold <type> <name>
+mallcop verify [--all]
+mallcop discover-app <app-name>
+```
+
+All commands output JSON by default. Use `--human` for readable output.
+
+## Deployment repo structure
+
+```
+my-security/
+  mallcop.yaml              # config: connectors, routing, secrets, budget
+  checkpoints.yaml          # connector cursors (last poll position)
+  events/                   # append-only JSONL, partitioned by source and month
+    azure-2026-03.jsonl
+    github-2026-03.jsonl
+  findings.jsonl            # detector output
+  costs.jsonl               # per-run token usage and cost tracking
+  baseline.json             # known actors, frequency tables, relationships
+  reputation.jsonl          # per-entity trust scores
+  skills.lock               # skill content hash pins
+```
+
+Everything is git-tracked. `git log events/` shows when events were ingested. `git diff findings.jsonl` shows what changed between runs.
+
+## Cost
+
+Near-$0. Mallcop is free and open source. The platform APIs it monitors are free tier. The only cost is LLM inference for the triage/investigate actors during escalation, controlled by configurable budget limits (default: 50k tokens/run). `mallcop init` estimates your steady-state costs based on discovered resources.
+
+## License
+
+Apache 2.0