xorcise 0.1.0__tar.gz

xorcise-0.1.0/.env.example

@@ -0,0 +1,34 @@
+# Copy to ~/.xorcise/.env (chmod 0600). Real values are never committed.
+#
+# Every setting is the field name from xorcise.core.config.Settings prefixed with
+# XORCISE_. Anything left unset falls back to the documented default, so the shortest
+# working file is just the three model_* lines below.
+
+# --- BYOM model (required for grading) ---------------------------------------
+# XORCISE bundles no model. Point these at any OpenAI-compatible endpoint — a hosted
+# provider, or something you serve yourself (vLLM, Ollama, LM Studio).
+XORCISE_MODEL_KEY=
+XORCISE_MODEL_BASE_URL=
+XORCISE_MODEL_NAME=
+# Raise this for slow or reasoning models — they can spend a while thinking before
+# emitting a verdict. Seconds; default 120.
+# XORCISE_MODEL_TIMEOUT_SECONDS=120
+
+# --- Persistence -------------------------------------------------------------
+# Defaults to sqlite:///<home>/xorcise.db, where <home> is ~/.xorcise unless
+# XORCISE_HOME says otherwise. Set this only to move the database elsewhere; a
+# server dialect additionally needs the matching extra (pip install "xorcise[postgres]").
+# XORCISE_DATABASE_URL=sqlite:////absolute/path/to/xorcise.db
+
+# --- Mission catalog ---------------------------------------------------------
+# Defaults to the XORCISE.AI catalog, which is what a fresh install browses and pulls
+# missions from. Point a dev build somewhere else here, or clear it to run fully
+# offline — the bundled missions/ bundles need no catalog at all. The UI's
+# connect/disconnect switch toggles access without discarding the endpoint.
+# XORCISE_CATALOG_URL=
+# XORCISE_CATALOG_KEY=
+
+# --- Attachment link signing -------------------------------------------------
+# A fresh random secret is generated per process when unset. Pin it only if you need
+# signed attachment URLs to survive a restart or to be shared between processes.
+# XORCISE_RUN_CONTROL_SIGNING_SECRET=

xorcise-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,26 @@
+# Code owners. With "Require review from Code Owners" in the branch ruleset, these paths
+# cannot merge without a maintainer's approval. See MAINTAINERS.md.
+#
+#   @guru-xorciseai      Guru Hariharaun      — author and maintainer
+#   @christo-xorciseai   Christo Joby Antony  — maintainer
+#
+# Both are on every rule so either can approve; a single owner would deadlock reviews.
+#
+# Two silent failure modes — neither reports an error at merge time:
+#   1. an owner without WRITE access to the repo is ignored;
+#   2. a handle that does not resolve is skipped, and the rule then protects nothing.
+# Check for GitHub's warning banner on this file after pushing.
+
+*                                @guru-xorciseai @christo-xorciseai
+
+# Supply-chain critical: a bad change here compromises every release, not just one feature.
+/.github/                        @guru-xorciseai @christo-xorciseai
+/.github/workflows/              @guru-xorciseai @christo-xorciseai
+/.github/workflows/release.yml   @guru-xorciseai @christo-xorciseai
+/pyproject.toml                  @guru-xorciseai @christo-xorciseai
+/hatch_build.py                  @guru-xorciseai @christo-xorciseai
+/uv.lock                         @guru-xorciseai @christo-xorciseai
+/scripts/                        @guru-xorciseai @christo-xorciseai
+/SECURITY.md                     @guru-xorciseai @christo-xorciseai
+/CODE_OF_CONDUCT.md              @guru-xorciseai @christo-xorciseai
+/LICENSE                         @guru-xorciseai @christo-xorciseai

xorcise-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,126 @@
+name: Bug report
+description: Something in XORCISE does not work the way it should.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug.
+
+        **Security vulnerabilities do not belong here.** If you have found a security issue,
+        please report it privately — see [SECURITY.md](../blob/main/SECURITY.md). Public
+        issues are visible to everyone, including people who would exploit the flaw.
+
+        Note that missions are **deliberately vulnerable**; that is their purpose.
+        Vulnerabilities inside a mission bundle are not XORCISE bugs.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you file
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: This is not a security vulnerability (those go to SECURITY.md).
+          required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: XORCISE version
+      description: Output of `xorcise --version`.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: How did you install XORCISE?
+      options:
+        - pip / uv from PyPI
+        - From a git checkout (editable install)
+        - From a built wheel
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: Include the version. On Linux, the distribution too.
+      placeholder: "Ubuntu 24.04 / macOS 15.1 / Windows 11 + WSL2"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`. XORCISE requires 3.12 or newer.
+      placeholder: "3.12.3"
+    validations:
+      required: true
+
+  - type: input
+    id: docker-version
+    attributes:
+      label: Docker version
+      description: >-
+        Output of `docker --version`. Required if the bug involves running a mission,
+        `xorcise up`, the runner, or the control plane. Write "n/a" if unrelated.
+      placeholder: "Docker version 27.3.1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: >-
+        Exact commands, in order. A bug someone else can reproduce gets fixed; one that only
+        happens on your machine usually does not.
+      placeholder: |
+        1. xorcise up
+        2. xorcise mission pull <name>
+        3. xorcise run create --mission <name> --agent <agent>
+        4. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happened
+      description: Include the full error message if there is one.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: >-
+        Relevant output. **Remove secrets first** — API keys, tokens, tailnet auth keys,
+        certificates, internal hostnames. This box renders as a code block automatically.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: Screenshots, related issues, workarounds you have found.
+    validations:
+      required: false

xorcise-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,26 @@
+# Issue-template chooser configuration.
+#
+# `blank_issues_enabled: false` forces every report through one of the structured forms. That
+# is not bureaucracy: the single biggest cost in triage is going back and forth asking for a
+# version number and a reproduction, and the forms collect both up front.
+#
+# The security link is the important one. It routes vulnerability reports to GitHub's private
+# advisory flow BEFORE someone posts an exploitable flaw in a public issue.
+blank_issues_enabled: false
+
+contact_links:
+  - name: 🔒 Report a security vulnerability (private)
+    # PLACEHOLDER: xorcise-ai/xorcise — substitute the real GitHub org/repo.
+    # Requires "Private vulnerability reporting" to be enabled in repository settings.
+    url: https://github.com/xorcise-ai/xorcise/security/advisories/new
+    about: >-
+      Never report a vulnerability in a public issue. Use GitHub's private advisory form so the
+      problem can be fixed before it is disclosed. See SECURITY.md for scope and what to include.
+
+  - name: 💬 Questions and general discussion
+    # PLACEHOLDER: xorcise-ai/xorcise. If GitHub Discussions is not enabled, remove this entry
+    # rather than leaving a link that 404s.
+    url: https://github.com/xorcise-ai/xorcise/discussions
+    about: >-
+      Usage questions, ideas that are not yet a concrete feature request, and "am I doing this
+      right?" — these get better answers in Discussions than in the issue tracker.

xorcise-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,85 @@
+name: Feature request
+description: Suggest a capability or improvement for XORCISE.
+title: "[Feature]: "
+labels:
+  - feature
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. The most useful feature requests describe a **problem you
+        hit**, not just a solution you have in mind — that leaves room for a better design than
+        either of us had first.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you file
+      options:
+        - label: I searched existing issues and discussions and this is not a duplicate.
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: >-
+        What are you trying to do, and what stops you today? Concrete beats abstract:
+        "I cannot compare two agents across the same mission set without exporting to CSV
+        by hand" is far more useful than "reporting should be better".
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+      description: Your proposed solution, if you have one. Sketch the CLI or UI if it helps.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you have considered
+      description: Including workarounds you are using now.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which part of XORCISE does this affect?
+      multiple: true
+      options:
+        - CLI
+        - Web UI / frontend
+        - Runner / mission execution
+        - Control plane / networking
+        - Agent harness adapters
+        - Mission format or schema
+        - Grading / evaluation
+        - Reporting
+        - Packaging / installation
+        - Documentation
+        - Not sure
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: breaking
+    attributes:
+      label: Compatibility
+      options:
+        - label: >-
+            As far as I can tell, this would require a breaking change to an existing
+            interface (CLI options, config, mission schema, adapter contract, output format).
+          required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be willing to work on this myself.
+          required: false

xorcise-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,90 @@
+<!--
+Thanks for contributing to XORCISE.
+
+Nothing here is busywork: each item below maps to a check a reviewer would otherwise have to
+run by hand. Delete any section that genuinely does not apply, and say why.
+-->
+
+## What changed
+
+<!-- The change itself, in a sentence or two. -->
+
+## Why
+
+<!-- The problem this solves. Link an issue with "Closes #123" if there is one. If this is a
+     behaviour change, say what a user could not do before and can do now. -->
+
+## Testing
+
+<!-- What you actually ran, and what it printed. "Tests pass" is not evidence; a command and
+     its result is. -->
+
+```
+# e.g. uv run pytest -m unit -n auto
+```
+
+**Test lanes affected** (tick every lane your change could plausibly break):
+
+- [ ] `unit` — no Docker, fast
+- [ ] `adapters` — port/adapter contracts
+- [ ] `topology` — manifest / compose / import / extras parity
+- [ ] `integration` — needs Docker or a live server process
+- [ ] `e2e` — full `xorcise up` + scripted agent
+- [ ] `frontend` — Next.js typecheck / vitest
+
+> The `integration` and `e2e` lanes do **not** run on pull requests by default — they need a
+> Docker daemon and bind fixed ports. If your change touches the runner, the control plane,
+> networking, or `xorcise up`, ask a maintainer to add the **`full-ci`** label so those lanes
+> run on this PR before it merges.
+
+## User-facing impact
+
+- [ ] No user-visible change (internal refactor, tests, docs only)
+- [ ] Backwards-compatible addition (new command, new optional flag, new field)
+- [ ] **Breaking change** — describe the break and the migration path below
+
+<!-- Public interfaces include: CLI commands and options, configuration files, environment
+     variables, mission manifests and schema, agent/adapter contracts, documented Python
+     APIs, REST contracts, and machine-readable output formats. Changing any of these affects
+     the next version number — see CONTRIBUTING.md. -->
+
+## Documentation
+
+- [ ] No documentation change needed
+- [ ] Documentation updated in this PR
+- [ ] Documentation needed and tracked in a follow-up issue (link it)
+
+## Dependencies
+
+- [ ] No dependency changes
+- [ ] Dependencies changed **and** the lockfile is committed
+      (`uv lock` for Python, `npm install` for `frontend/` — CI runs `uv sync --locked` and
+      `npm ci`, which fail if a manifest and its lockfile disagree)
+
+## Checklist
+
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` pass
+- [ ] `uv run mypy` passes (strict)
+- [ ] `uv run lint-imports` passes (architecture layer rules)
+- [ ] Relevant test lanes pass locally
+- [ ] **No secrets, credentials, tokens, keys, internal hostnames or customer data** appear in
+      the diff — including in test fixtures, logs and comments
+- [ ] No references to internal-only systems (private trackers, internal URLs, internal
+      process names) in code or documentation
+
+## Release notes
+
+<!-- Maintainers: apply ONE of these labels so this PR lands in the right section of the
+     generated release notes (.github/release.yml):
+       breaking-change · feature · enhancement · bug · security · documentation ·
+       dependencies · internal · skip-release-notes
+-->
+
+---
+
+By opening this pull request you agree that your contribution is licensed under the
+[Apache License 2.0](../LICENSE), and that you have read the
+[Code of Conduct](../CODE_OF_CONDUCT.md).
+
+**Found a security vulnerability?** Do not open a pull request or a public issue — follow
+[SECURITY.md](../SECURITY.md) instead.

xorcise-0.1.0/.github/codeql/codeql-config.yml

@@ -0,0 +1,11 @@
+# CodeQL analysis config. Note this is not the workflow's `paths-ignore`, which only decides
+# whether the workflow runs — this is what removes code from the database.
+name: "XORCISE CodeQL config"
+
+paths-ignore:
+  # Mission bundles are deliberately vulnerable: SQL injection, weak crypto and hardcoded flags
+  # are the content, not defects. Scanning them buries real findings under intentional ones.
+  # Harmless to keep if missions/ is later removed — an exclusion for a missing path is a no-op.
+  - missions
+  # Generated Next.js bundle. The authored sources under frontend/ are analysed instead.
+  - src/xorcise/core/frontend/_static

xorcise-0.1.0/.github/dependabot.yml

@@ -0,0 +1,101 @@
+# Dependency updates.
+#
+# The `github-actions` ecosystem is the security-critical one: every `uses:` is pinned to a
+# commit SHA, and Dependabot is what stops those pins going stale. `ignore` only suppresses
+# version-bump PRs — security alerts and fixes still arrive.
+version: 2
+
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    # Supply-chain maturity window: never adopt a release in its first 7 days.
+    #
+    # The attack this blocks is a compromised or hijacked package publishing a malicious
+    # version. Those are typically caught and yanked within hours-to-days, so the danger
+    # window is the release's infancy — precisely when an eager auto-bump would take it.
+    # Waiting lets the ecosystem find the problem for us; a version still standing after a
+    # week has been exercised by thousands of other installs.
+    #
+    # This deliberately applies to VERSION updates only. GitHub does not apply cooldown to
+    # Dependabot SECURITY updates, which is the behaviour we want: a fix for a known CVE
+    # must not sit in a queue for a week. Fast for fixes, patient for features.
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+    groups:
+      python-minor-patch:
+        update-types:
+          - minor
+          - patch
+    ignore:
+      # opentelemetry-proto is pinned exactly: it decodes the OTLP wire format, so a mismatch
+      # corrupts traces rather than raising an import error. Majors only — minor/patch still flow.
+      - dependency-name: opentelemetry-*
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: npm
+    directory: /frontend
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    # Supply-chain maturity window: never adopt a release in its first 7 days.
+    #
+    # The attack this blocks is a compromised or hijacked package publishing a malicious
+    # version. Those are typically caught and yanked within hours-to-days, so the danger
+    # window is the release's infancy — precisely when an eager auto-bump would take it.
+    # Waiting lets the ecosystem find the problem for us; a version still standing after a
+    # week has been exercised by thousands of other installs.
+    #
+    # This deliberately applies to VERSION updates only. GitHub does not apply cooldown to
+    # Dependabot SECURITY updates, which is the behaviour we want: a fix for a known CVE
+    # must not sit in a queue for a week. Fast for fixes, patient for features.
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+    groups:
+      frontend-minor-patch:
+        update-types:
+          - minor
+          - patch
+
+  # Grouped into one PR: a single reviewable PR actually gets merged, which is what keeps the
+  # SHA pins current.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    # Supply-chain maturity window: never adopt a release in its first 7 days.
+    #
+    # The attack this blocks is a compromised or hijacked package publishing a malicious
+    # version. Those are typically caught and yanked within hours-to-days, so the danger
+    # window is the release's infancy — precisely when an eager auto-bump would take it.
+    # Waiting lets the ecosystem find the problem for us; a version still standing after a
+    # week has been exercised by thousands of other installs.
+    #
+    # This deliberately applies to VERSION updates only. GitHub does not apply cooldown to
+    # Dependabot SECURITY updates, which is the behaviour we want: a fix for a known CVE
+    # must not sit in a queue for a week. Fast for fixes, patient for features.
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - internal
+    groups:
+      github-actions:
+        patterns:
+          - "*"

xorcise-0.1.0/.github/release.yml

@@ -0,0 +1,56 @@
+# Generated release-notes configuration.
+#
+# NOT a workflow. GitHub reads this file when `gh release create --generate-notes` runs (see
+# .github/workflows/release.yml) and uses it to group merged pull requests into sections.
+#
+# This is what makes "merge ten PRs, release once" produce a readable changelog: each PR is
+# filed by its label, so the notes for v0.2.0 arrive already sorted into breaking changes,
+# features, fixes and so on — rather than a flat list of commit subjects.
+#
+# Labelling a PR is therefore part of reviewing it. An unlabelled PR still appears, under
+# "Other changes".
+changelog:
+  exclude:
+    labels:
+      # Routine noise that should not appear in user-facing notes.
+      - skip-release-notes
+  categories:
+    # Order matters — this is the order sections appear in the notes. Breaking changes go
+    # first because they are the only thing a user MUST read before upgrading.
+    - title: ⚠️ Breaking changes
+      labels:
+        - breaking-change
+
+    - title: 🚀 New features
+      labels:
+        - feature
+
+    - title: ✨ Enhancements
+      labels:
+        - enhancement
+
+    - title: 🐛 Bug fixes
+      labels:
+        - bug
+
+    - title: 🔒 Security
+      labels:
+        - security
+
+    - title: 📚 Documentation
+      labels:
+        - documentation
+
+    - title: 📦 Dependencies
+      labels:
+        - dependencies
+
+    - title: 🔧 Internal
+      labels:
+        - internal
+
+    # Catch-all. `*` matches any PR not already claimed by a category above, so nothing is
+    # ever silently dropped from the notes.
+    - title: Other changes
+      labels:
+        - "*"