cmdscope 0.1.0__py3-none-any.whl

cmdscope-0.1.0.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: cmdscope
+Version: 0.1.0
+Summary: Run a command and see what it changed: files, processes, and network, locally and privately.
+Author: CmdScope contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SouzaF19/cmdscope
+Project-URL: Repository, https://github.com/SouzaF19/cmdscope
+Project-URL: Issues, https://github.com/SouzaF19/cmdscope/issues
+Project-URL: Changelog, https://github.com/SouzaF19/cmdscope/blob/main/CHANGELOG.md
+Keywords: observability,command-line,filesystem,process-monitoring,network-monitoring,audit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil<8,>=5.9
+Requires-Dist: watchdog<8,>=4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# CmdScope
+
+**Run a command and see what it changed — files, processes, and network — locally and privately.**
+
+CmdScope executes a command inside an observation session and records what it can actually
+see: files created, modified, or deleted under the directories you watch, the process tree
+it spawns, and the network endpoints it opens. When the command finishes, CmdScope prints a
+report and stores the session in a local SQLite database so you can compare runs later.
+
+```console
+$ cmdscope run -- npm install
+
+CMDSCOPE - EXECUTION REPORT
+======================================================================
+Session:      S000001
+Command:      npm install
+Directory:    C:\work\my-project
+Platform:     windows
+Started:      2026-11-08 10:45:36 UTC
+Duration:     12.43 s
+Exit status:  0
+Status:       completed
+
+FILESYSTEM
+  Watch roots: C:\work\my-project
+  Created:     184
+  Modified:    12
+  Deleted:     0
+  + node_modules\package\package.json (1.2 KB)
+  ~ package-lock.json (48.7 KB)
+
+PROCESSES
+  Started:       2
+  Finished:      2
+  Still running: 0
+  [pid 8124] started: node C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js install
+
+NETWORK
+  Connections observed: 1
+  [pid 8124] node: 10.0.0.14:52344 -> 104.16.24.35:443 (TCP, ESTABLISHED)
+
+COLLECTORS
+  filesystem   ok        backend=native, watch_roots=['C:\\work\\my-project']
+  network      ok        connections_observed=1
+  processes    ok        observed_processes=4, still_running=0
+
+SUMMARY
+  199 events observed in this session.
+  196 filesystem changes, 2 processes started, 1 network connection.
+
+LIMITATIONS
+  - Only changes under the configured watch roots are observed.
+  - Processes and sockets are sampled; short-lived ones can be missed.
+  - File contents are never captured.
+  - CmdScope observability is not sandboxing or isolation.
+  - Runtime environment mutations are not observable externally.
+
+Generated locally by CmdScope. No data was transmitted.
+```
+
+> The numbers above are illustrative. Every value in a real report comes from an
+> observation made during that session.
+
+## The problem
+
+Installing a package, running a migration, or executing a build script usually leaves you
+guessing. `strace` and `Procmon` are powerful but heavy, privileged, platform-specific, and
+not session-oriented. CmdScope offers a small, honest, cross-platform tool for the common
+question: *"what did that command actually do to my machine?"*
+
+CmdScope is an **observability** tool. It is **not** a sandbox, a permission system, or a
+malware detector. The monitored command runs with your normal permissions and is not
+restricted in any way.
+
+## Main features
+
+- **Filesystem observation** — metadata changes (created / modified / deleted) under explicit
+  watch roots, using native OS events (`ReadDirectoryChangesW`, `inotify`, `FSEvents`) with a
+  polling fallback.
+- **Process tree observation** — the root process and the descendants it spawns, with
+  start/finish observations and command lines.
+- **Network observation** — TCP/UDP endpoints attributed to the processes of the session.
+- **Session history** — every run is stored in a local SQLite database.
+- **Comparison** — `cmdscope compare` diffs two sessions by normalized paths and event
+  signatures.
+- **Reports** — terminal, JSON, and self-contained HTML (no scripts, no external assets).
+- **Privacy by default** — no telemetry, no uploads, no file contents, and automatic
+  redaction of sensitive flags and environment variables.
+- **Honest capabilities** — every collector reports its state and blind spots in the report.
+
+## Installation
+
+```console
+$ pip install cmdscope
+```
+
+From a checkout:
+
+```console
+$ python -m pip install -e ".[dev]"
+$ cmdscope --version
+```
+
+Python 3.11 or newer is required.
+
+## Requirements
+
+| Requirement | Notes |
+| --- | --- |
+| Python | 3.11+ (tested on 3.13) |
+| Dependencies | `psutil`, `watchdog` (installed automatically) |
+| Privileges | none required; CmdScope never elevates on its own |
+
+The database lives in the per-user data directory:
+
+| Platform | Default database |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\cmdscope\cmdscope.db` |
+| Linux | `$XDG_DATA_HOME/cmdscope/cmdscope.db` (or `~/.local/share/cmdscope/cmdscope.db`) |
+| macOS | `~/Library/Application Support/cmdscope/cmdscope.db` |
+
+Use `cmdscope doctor` to see the resolved paths and the capabilities of your machine.
+
+## Usage
+
+```console
+# Observe a command in the current directory
+cmdscope run -- npm install
+
+# Watch extra directories (repeatable)
+cmdscope run --watch ./src --watch ./config -- python app.py
+
+# Ignore noisy paths
+cmdscope run --ignore "*.log" --ignore "node_modules/**" -- pytest -q
+
+# Pass environment variables to the command (values are redacted in reports)
+cmdscope run --env API_TOKEN=secret -- node deploy.js
+
+# Skip collectors you do not need
+cmdscope run --no-network -- python build.py
+
+# Session history
+cmdscope sessions
+cmdscope sessions --json
+
+# Inspect one session
+cmdscope show S000001
+cmdscope show 1 --include-environment
+
+# Reports
+cmdscope report S000001
+cmdscope report S000001 --format json
+cmdscope report S000001 --format html --output report.html
+
+# Compare two runs
+cmdscope compare S000001 S000002
+cmdscope compare S000001 S000002 --format json
+
+# Environment diagnostics and configuration
+cmdscope doctor
+cmdscope config --path
+cmdscope config --init
+```
+
+Global options (`--config`, `--db`, `--no-color`, `--verbose`) must be placed **before** the
+subcommand:
+
+```console
+cmdscope --db ./local.db run -- python app.py
+```
+
+### What is observed, and where
+
+- The **watch root** defaults to the current working directory. Use `--watch` or
+  `filesystem.watch` in the configuration file to add others.
+- Files are observed **by metadata only**: path, size, modification time, and whether the
+  entry is a directory. Contents are never read.
+- Events are *observed during the session* in the watched roots. CmdScope does not prove
+  causality: another process writing into the same directory at the same time will also
+  show up.
+- CmdScope's own database files are automatically excluded from the report, even when the
+  database lives inside a watch root.
+
+## Supported systems
+
+| Platform | Status in 0.1.x |
+| --- | --- |
+| Windows 10 / 11 | **Validated manually** on Windows 11 with Python 3.13, plus CI |
+| Linux | Implemented and exercised by CI (Ubuntu); not manually validated in this release |
+| macOS | Implemented and exercised by CI (macOS); experimental |
+
+The collectors are portable, but the underlying observation mechanisms differ. See
+[docs/collectors.md](docs/collectors.md) for the per-platform behaviour and the exact
+blind spots of each collector.
+
+## Known limitations
+
+- **Not a sandbox.** CmdScope does not restrict, isolate, or mediate the monitored command.
+- **Not syscall tracing.** CmdScope does not use `ptrace`, eBPF, ETW, or a kernel driver. It
+  cannot see file access, registry writes, or syscalls that do not change observed state.
+- **Limited filesystem coverage.** Only the configured watch roots are observed. Changes
+  anywhere else on the system are invisible.
+- **Sampling.** Processes and sockets are discovered by polling. A child process or a
+  connection that lives entirely between two polls can be missed.
+- **Network attribution needs privileges on macOS.** Unprivileged processes cannot see
+  socket owners there; CmdScope marks the network collector as `degraded` instead of
+  pretending it observed nothing.
+- **No runtime environment visibility.** Only the initial environment diff handed to the
+  child is recorded. Mutating `environ` inside a running process cannot be observed.
+- **No attribution of causes.** The report says what was observed, not which process caused
+  it, except for processes that CmdScope itself launched.
+- **Partial snapshots.** If a watch root is larger than `filesystem.max_files`, CmdScope
+  reports a degraded collector instead of guessing which files were deleted.
+
+## Privacy and security
+
+- All data stays on your machine. CmdScope has no network client, no telemetry, and no
+  analytics.
+- File contents are never captured.
+- Command lines and environment variables are redacted before they are stored
+  (`--token`, `--password`, `*_SECRET`, `*_TOKEN`, URL credentials, `Authorization`
+  headers, and similar).
+- The monitored command runs with your permissions. CmdScope never elevates, never installs
+  drivers, and never modifies the files it watches.
+- Details: [docs/privacy.md](docs/privacy.md).
+
+## Architecture
+
+```text
+cli ──► core.engine ──► collectors ──► core.events (typed events)
+                │                              │
+                └──────────► storage.sqlite ◄──┘
+                                  │
+                            analysis ──► reports
+```
+
+- `core/` — event models, session lifecycle, collector interface, runner.
+- `collectors/` — filesystem, process, and network observation.
+- `platforms/` — OS capabilities, data directories, command launch details.
+- `storage/` — SQLite persistence and the event writer thread.
+- `analysis/` — summaries and session comparison.
+- `reports/` — terminal, JSON, and HTML rendering.
+- `cli.py` — argument parsing and user-facing behaviour.
+
+See [docs/architecture.md](docs/architecture.md) for details and
+[docs/collectors.md](docs/collectors.md) for the guide to adding a new collector.
+
+## Configuration
+
+Optional TOML file, searched in this order: `--config <path>`, `$CMDSCOPE_CONFIG`,
+`./cmdscope.toml`, then the per-user config directory.
+
+```toml
+[filesystem]
+enabled = true
+watch = []
+ignore = [".git", "__pycache__", "*.pyc"]
+max_files = 100000
+poll_interval = 1.0
+native_events = true
+
+[processes]
+enabled = true
+poll_interval = 0.5
+
+[network]
+enabled = true
+poll_interval = 0.25
+
+[privacy]
+capture_environment = true
+show_environment = false
+
+[storage]
+max_sessions = 0
+max_events = 100000
+
+[report]
+max_events = 500
+format = "terminal"
+```
+
+Run `cmdscope config --init` to write a commented template. Full reference:
+[docs/configuration.md](docs/configuration.md).
+
+## Roadmap
+
+- [x] Session runner with filesystem, process, and network collectors
+- [x] Local SQLite history, session comparison, JSON/HTML reports
+- [x] Privacy-first sanitization and `cmdscope doctor`
+- [ ] Optional ETW/eBPF backends for deeper coverage (opt-in, clearly marked as elevated)
+- [ ] Registry and environment-diff collectors on Windows
+- [ ] Session diffing in HTML reports
+- [ ] Signed releases and reproducible-build verification
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first; it documents
+the engineering rules, quality gates, and the workflow we use to keep CmdScope
+dependable.
+
+```console
+$ python -m pip install -e ".[dev]"
+$ ruff check src tests
+$ ruff format --check src tests
+$ mypy src/cmdscope
+$ pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cmdscope-0.1.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+cmdscope/__init__.py,sha256=7f8zUSNea4LLkcNM6fuRsQi1oiCQ7sJxFmTQ1BQVbe8,337
+cmdscope/__main__.py,sha256=3Qwvw6Y8tOIZdQ3HIiefrqIs2FKKgvuqr0lBz9Qyn5A,221
+cmdscope/cli.py,sha256=9NNZsHqc4eU3zNtwN8gFCKQN9s98skOFIihFUt1sd10,19180
+cmdscope/config.py,sha256=XuV4TCMBIFwHKK_RLV8l5UU3pm2ln--3BWPOmfzeRCI,15752
+cmdscope/diagnostics.py,sha256=dUcQgBi_KEyW8k9e9f0bnwIpFOcBzPposfiBsmTfK3c,6633
+cmdscope/errors.py,sha256=0qpxtZ7TlWDS8BUTwWg7IXwbdwZ7k3Px9NhABf8ObH4,1048
+cmdscope/privacy.py,sha256=Q5eiIqUWFSMSA-fMdCZ-tqwJ8cIq2MfitxaLR0lcdnU,4859
+cmdscope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cmdscope/analysis/__init__.py,sha256=DZrAxHYuskzQqY9o3dGLldDrUlX07X_52CKdtw8XlSw,24
+cmdscope/analysis/comparison.py,sha256=GxcNcG4gMz8qtvQYCWfveeVtxai1Llffx6pN5ZpdhAU,4515
+cmdscope/analysis/summary.py,sha256=-KmjOl0vGnHW_FvW6aF4Z9MXAzkIQy4b4ps2jz87dGQ,1542
+cmdscope/collectors/__init__.py,sha256=Z0_PSO7422kri9w6DT3HIBYA8_IxeSa6tQaRXQkyEy0,67
+cmdscope/collectors/filesystem.py,sha256=xhAhcwPdfbOzzAy3hjsZ909ASvoE6rfn0uNg2rxNhgY,13776
+cmdscope/collectors/network.py,sha256=zONQeHsMKKqh6W6yLLDmi6jP8ZcxzEFMeLOb_cGvlkw,6532
+cmdscope/collectors/processes.py,sha256=mIEJR7rpkOMhZzYDV51OogzwJR5eHMrJa5Dht6aLrws,11583
+cmdscope/core/__init__.py,sha256=h77irJhljY9ItqlJ8_flWEFmSWLge19YVByMlzHpp6Q,34
+cmdscope/core/collector.py,sha256=GKlBT6XfT-XOsHcI1nR4bDNiFPEixuQP-47Ryx6RYUM,1433
+cmdscope/core/engine.py,sha256=rFk6HxsJ65GcApY3ewckdTvavj8RcpjAVWARfzmyG2k,17498
+cmdscope/core/events.py,sha256=zuAgnc8cFj1UJ8GVwzYDAlB1ZivHUGkRpCHMGq_gvdg,3029
+cmdscope/core/ignore.py,sha256=a8xPp7ik9roSbBvm5AnBi_QZ_aHCSMGKFCzeqMbWPCw,1669
+cmdscope/core/registry.py,sha256=wKT80arTPg6tDxx4rKZ1xoblKDegOvvBpVcAdTzrEPQ,910
+cmdscope/core/session.py,sha256=XdfZ-2gIGLAboNTBtAVOWgwwGdjfrOobnemWnoF_cyw,2079
+cmdscope/platforms/__init__.py,sha256=ib4PVWFNXqvOK8afQGo8aUxjG-SPKAAgjlsbJ-lX5sY,1423
+cmdscope/platforms/base.py,sha256=Rl1-9u8pUOYGEDrc809MBcUx76n_PqHyMsr_M8jPbLc,4894
+cmdscope/platforms/linux.py,sha256=R37Y6Rz4pt5hwb0XhtqZEwly50f-SAcsd11LRHpsmfM,1152
+cmdscope/platforms/macos.py,sha256=_PpOSzF6EqK8efjxridC4Iy-MmxuWLXf9lezQYYLnxA,976
+cmdscope/platforms/windows.py,sha256=A-YCHWhcob9nMYA2fyxqKJAexs6ViVIYVAMUikbVgXI,1136
+cmdscope/reports/__init__.py,sha256=bmQ3dGBiHqSPwumamEebbTyZSdWgUDms_jPjo1MBB0Y,24
+cmdscope/reports/html.py,sha256=z7N35vnAg77aSapzPVo3xDPFb2uoi0ADPZBzaJe7UoU,11202
+cmdscope/reports/json_report.py,sha256=kjMbq6q087yDRWnlxCOAufSj-IoC2233IcG81YV62lM,4928
+cmdscope/reports/terminal.py,sha256=SxKZTwy_i-E5wnYhPtK0fBcU1iBywktx6kQwevP5hWk,14819
+cmdscope/storage/__init__.py,sha256=UvHvinbkEHGq7blHfhHQ52Axh47-MXDxCZcmJzuHxcI,192
+cmdscope/storage/sqlite.py,sha256=ULBlEGI6OzC6lXNcOYSs8Wj0ykF-dfBp16tyPmgRn5o,16886
+cmdscope/storage/writer.py,sha256=qFPORffiYvFjPmzE6twrvvfFVziusf_lBtUtfZmyuLY,3578
+cmdscope-0.1.0.dist-info/licenses/LICENSE,sha256=7NgKnaKuHRUop_ykNm4PvXCJGCok_mRxNEu6a5oLIco,1078
+cmdscope-0.1.0.dist-info/METADATA,sha256=Qt9oRk3SaY6bjb3TDMPvsbrLDnpJBocSi8zTwyO9ryQ,12766
+cmdscope-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+cmdscope-0.1.0.dist-info/entry_points.txt,sha256=nYBR2OQyUajEDSmPz9NvbzDj_JcdWXUxD7N1p0pmx3I,47
+cmdscope-0.1.0.dist-info/top_level.txt,sha256=h9UCflaMxhX5Pan9_et8Vvhj5f9UNPuGiSxziEtot9s,9
+cmdscope-0.1.0.dist-info/RECORD,,

cmdscope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cmdscope-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cmdscope = cmdscope.cli:main

cmdscope-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CmdScope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmdscope-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmdscope