Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ The repository does not claim live Windows acceptance for these capabilities.

## Build the bootstrap

Go 1.26.9 or newer is required.
Go 1.26.10 or newer is required.

```sh
go test ./...
Expand Down
2 changes: 1 addition & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Toolchain

- Go 1.26.9 or newer.
- Go 1.26.10 or newer.
- `golangci-lint` v2.13.2 for the full lint target. Keep the local and CI versions aligned.
- ShellCheck for the small repository shell-tooling surface.
- GoReleaser v2 for packaging checks.
Expand Down
26 changes: 26 additions & 0 deletions docs/guest-desktop.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,32 @@ Issuing a grant does not install the guest driver. Provision it using `desktop_a
A driver update must remove the old verified installation with its matching build before
provisioning the new build. Foreign or modified installations are refused.

## Persistent disposable VM authority

For an owner-controlled disposable test VM, the operator can enable persistent VM authority:

```sh
amc desktop enable --target lab-vm --for-mcp --persistent-vm \
--acknowledge-external-effects \
--reason 'authorize autonomous work on the disposable test VM' \
--idempotency-key persistent-lab-example
```

This grant has no time-based expiry. It survives daemon restarts and authorizes guest file and
script operations, terminal sessions, console and desktop actions, VM start/stop, and checkpoint
creation/restoration on the exact enrolled VM. A separate grant without `--for-mcp` enables the
operator CLI. Agents do not need to request one-use approvals for those operations. The service
derives their exact approvals from the stored operator grant and preserves normal audit, receipts,
actor scopes, deadlines, and idempotency checks. Actual safety classification remains unchanged;
enabling this mode does not declare external effects contained or invent a rollback checkpoint.

Use `amc desktop status` to discover the current grant for the caller and selected target, or
provide `--lab-grant-id` to inspect a specific grant. The existing `desktop disable` command
revokes persistent authority. Clearing or replacing the enrollment also invalidates it, including
when the same VM is enrolled again. Other VMs, host administration, enrollment changes, credential
configuration, and approval issuance receive no authority from this mode. Without `--persistent-vm`,
the existing bounded console/desktop grant behavior is unchanged.

## Agent interaction loop

1. Call `desktop_observe`. It returns a PNG content block, frame identity, native and
Expand Down
15 changes: 15 additions & 0 deletions docs/guest-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ Each operation carries a reason, idempotency key and exact deadline. On protecte
operator issues a one-use approval for the exact operation and beneficiary. Issuance supports the
current operator or the canonical local MCP actor; MCP cannot issue approvals.

An operator may instead enable [persistent disposable VM authority](guest-desktop.md#persistent-disposable-vm-authority)
once for the enrolled test VM and beneficiary. The daemon then supplies exact operation approvals
automatically until that authority is revoked or the enrollment changes.

## Operation contracts

| Operation | Result and boundary |
Expand All @@ -31,6 +35,13 @@ current operator or the canonical local MCP actor; MCP cannot issue approvals.
| `exec` | Runs a bounded UTF-8 script in the persistent runspace, with bounded output and a final receipt. |
| `remove-owned` | Removes up to 128 referenced original files in one request; reports accepted deletion and observed absence separately. |

MCP tools advertise operation-specific input schemas. `prepare` requires `max_output: 0` and no
source, destination, or artifact IDs. `put` also requires zero output and no artifact IDs or
destination. `get` requires one artifact ID, a new local destination, and positive output limit.
`exec` requires a local script, a new destination, and a positive output limit up to 16 MiB, with
no artifact IDs. `remove-owned` requires one or more artifact IDs and zero output, without local
source or destination paths. Invalid shapes are rejected before dispatch with an actionable error.

Transfers use bounded binary buffers. File content is not encoded into terminal commands, clipboard
messages or control JSON. Script and command output limits are 16 MiB each. Download and command
output are quarantined in private host files and released only after integrity checks and a durable
Expand All @@ -48,6 +59,10 @@ result closes the affected worker and preserves durable uncertainty. Retrying an
returns receipt metadata; it does not repeat effects or replay output bytes. Download publication
requires verified bytes and the final result, and never replaces an existing local destination.

Known validation and authorization failures retain their typed categories across daemon, CLI and
MCP. Arbitrary provider messages are not exposed. A known rejection is distinct from an uncertain
transport outcome; incomplete responses still require inspecting the receipt before another action.

The low-level Go `Client.GuestOperation` method writes provisional output to its supplied sink
before validating the final trailer. Callers must keep that sink unpublished and discard its
contents on any error. CLI and MCP use `GuestOperationToFile`, which quarantines output and
Expand Down
2 changes: 1 addition & 1 deletion docs/ssh-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ All session mutations (`session.open`, `session.write`, `session.control`, `sess
1. **Dynamic Safety Resolution**:
- The safety resolver inspects the target machine's server-owned `config.json` (`external_effects_contained`, `rollback_checkpoint_id`) and queries the Hyper-V backend (`ListCheckpoints`).
- If external effects are contained and the rollback checkpoint exists and is verified in Hyper-V, the operation is classified as `ClassReversibleMutation` with the checkpoint GUID as `rollbackRef`.
- If external effects are not contained or the rollback checkpoint is missing/invalid, the operation is classified as `ClassDestructivePrivileged`, requiring an explicit, unconsumed operator approval record.
- If external effects are not contained or the rollback checkpoint is missing/invalid, the operation is classified as `ClassDestructivePrivileged`, requiring an unconsumed operator approval record. An operator-enabled [persistent VM grant](guest-desktop.md#persistent-disposable-vm-authority) supplies exact approvals automatically for its enrolled VM and beneficiary, without another human prompt.
2. **Host Mutation Lease**:
- Every session mutation acquires a host lease before reading containment configuration or
querying the configured checkpoint. The same lease remains held through guest effect and
Expand Down
9 changes: 9 additions & 0 deletions docs/threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,15 @@ logical principal identity of the caller:
untrusted agent from implicitly inheriting the operator's OS-level rights simply by communicating
through a local adapter.

An operator can explicitly enable persistent authority for an enrolled disposable VM and a
specific beneficiary. This uses the protected lab-grant store and derives exact server-owned
operation approvals; it does not change the caller identity or declare external effects contained.
The opt-in `persistent-vm` mode covers guest operations, terminal sessions, VM console/desktop,
start/stop and checkpoint create/restore. It has no time-based expiry, is revocable, and is bound to
the current enrollment epoch. It grants no host administration, enrollment/configuration changes
or approval-issuance scope. Default and legacy bounded-grant behavior remain unchanged. See
[persistent disposable VM authority](guest-desktop.md#persistent-disposable-vm-authority).

### Authenticated Caller versus Effective Actor

- **Authenticated Caller**: The direct transport entity communicating with `amcd` (e.g., the
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module github.com/Horcag/agent-machine-control

go 1.26.9
go 1.26.10

require (
github.com/modelcontextprotocol/go-sdk v1.8.0
Expand Down
66 changes: 46 additions & 20 deletions internal/app/console_lab.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,30 +30,25 @@ func (s *ConsoleService) IssueLabGrant(ctx context.Context, actor domain.ActorCo
if err != nil {
return grant, result, err
}
if err := s.requireLabSafety(ctx, resolution, req.AcknowledgeExternalEffects); err != nil {
if err := s.requireGrantSafety(ctx, resolution, req.Mode, req.AcknowledgeExternalEffects); err != nil {
return grant, result, err
}
existing, err := s.loadLabGrant(ctx, id)
if err != nil && !errors.Is(err, os.ErrNotExist) {
return grant, result, err
}
now := s.recovery.now()
grant = ConsoleLabGrant{AcknowledgeExternalEffects: req.AcknowledgeExternalEffects, SchemaVersion: 1, GrantID: id, Target: domain.MachineRef(resolution.Locator.String()), EnrollmentIdentity: identity,
Issuer: actor.EffectiveActor, Beneficiary: beneficiary, Reason: req.Reason, IdempotencyKey: req.IdempotencyKey,
IssuedAt: now, ExpiresAt: now.Add(time.Duration(req.ValidForMillis) * time.Millisecond)}
if err == nil {
grant.IssuedAt, grant.ExpiresAt = existing.IssuedAt, existing.ExpiresAt
if grant != existing || existing.ExpiresAt.Sub(existing.IssuedAt).Milliseconds() != req.ValidForMillis {
return ConsoleLabGrant{}, result, receipt.ErrIdempotencyCollision
}
if err := s.validateLabBinding(ctx, existing); err != nil {
return ConsoleLabGrant{}, result, err
}
grant, err = s.prepareLabGrant(ctx, actor, req, beneficiary, resolution, identity, id, existing, err == nil)
if err != nil {
return ConsoleLabGrant{}, result, err
}
op := labGrantOperation("console.lab.grant.issue", actor, grant, req.Reason, req.IdempotencyKey, grant.ExpiresAt)
issuanceDeadline := grant.ExpiresAt
if grant.Mode == ConsoleLabModePersistentVM {
issuanceDeadline = grant.IssuedAt.Add(5 * time.Minute)
}
op := labGrantOperation("console.lab.grant.issue", actor, grant, req.Reason, req.IdempotencyKey, issuanceDeadline)
op.Parameters = map[string]any{"grant_id": id, "beneficiary": string(beneficiary), "enrollment_identity": identity, "expires_at": grant.ExpiresAt.UTC().Format(time.RFC3339Nano), "acknowledge_external_effects": grant.AcknowledgeExternalEffects}
result, resultErr = s.persistLabAuthority(ctx, op, grant.IssuedAt, id, func() error {
if err == nil {
if existing.GrantID != "" {
return nil
}
return s.writeLabDocument(ctx, id, ".json", grant)
Expand Down Expand Up @@ -91,7 +86,7 @@ func labGrantID(actor domain.ActorID, key string) string {
}

func (s *ConsoleService) labIdentity(ctx context.Context, reference string) (TargetResolution, string, error) {
if s.labEnrollment == nil || s.labSafety == nil {
if s.labEnrollment == nil {
return TargetResolution{}, "", ErrInvalidConsoleLabGrant
}
resolution, err := s.target.ResolveTarget(ctx, reference)
Expand Down Expand Up @@ -137,7 +132,7 @@ func (s *ConsoleService) resolveLabBinding(ctx context.Context, grant ConsoleLab

func (s *ConsoleService) resolveLabBindingWithResolution(ctx context.Context, grant ConsoleLabGrant, observed *TargetResolution) (TargetResolution, error) {
now := s.recovery.now()
if now.Before(grant.IssuedAt) || !now.Before(grant.ExpiresAt) {
if now.Before(grant.IssuedAt) || (grant.Mode == "" && !now.Before(grant.ExpiresAt)) {
return TargetResolution{}, ErrInvalidConsoleLabGrant
}
revoked, err := s.labRevoked(ctx, grant.GrantID)
Expand All @@ -150,7 +145,7 @@ func (s *ConsoleService) resolveLabBindingWithResolution(ctx context.Context, gr
resolution, identity, err = s.labIdentity(ctx, string(grant.Target))
} else {
resolution = *observed
if s.labEnrollment == nil || s.labSafety == nil || resolution.Validate() != nil {
if s.labEnrollment == nil || resolution.Validate() != nil {
return TargetResolution{}, ErrInvalidConsoleLabGrant
}
identity, err = s.labEnrollment(ctx, domain.MachineRef(resolution.Locator.String()))
Expand All @@ -161,7 +156,7 @@ func (s *ConsoleService) resolveLabBindingWithResolution(ctx context.Context, gr
if err != nil || resolution.Locator.String() != string(grant.Target) || identity != grant.EnrollmentIdentity {
return TargetResolution{}, ErrInvalidConsoleLabGrant
}
return resolution, s.requireLabSafety(ctx, resolution, grant.AcknowledgeExternalEffects)
return resolution, s.requireGrantSafety(ctx, resolution, grant.Mode, grant.AcknowledgeExternalEffects)
}

func labGrantOperation(kind domain.OperationKind, actor domain.ActorContext, grant ConsoleLabGrant, reason, key string, deadline time.Time) domain.Operation {
Expand Down Expand Up @@ -198,8 +193,39 @@ func validateLabIssueRequest(actor domain.ActorContext, req ConsoleLabGrantIssue
if err := labOperator(actor); err != nil {
return "", err
}
if domain.ValidateReason(req.Reason) != nil || domain.ValidateIdempotencyKey(req.IdempotencyKey) != nil || req.ValidForMillis < 1000 || req.ValidForMillis > MaxConsoleLabGrantValidity.Milliseconds() {
if domain.ValidateReason(req.Reason) != nil || domain.ValidateIdempotencyKey(req.IdempotencyKey) != nil || (req.Mode == "" && (req.ValidForMillis < 1000 || req.ValidForMillis > MaxConsoleLabGrantValidity.Milliseconds())) || (req.Mode != "" && (req.Mode != ConsoleLabModePersistentVM || !req.AcknowledgeExternalEffects)) {
return "", ErrInvalidConsoleLabGrant
}
return labBeneficiary(actor, req.Beneficiary)
}

func (s *ConsoleService) requireGrantSafety(ctx context.Context, resolution TargetResolution, mode string, acknowledge bool) error {
if mode == ConsoleLabModePersistentVM {
return nil
}
if s.labSafety == nil {
return ErrInvalidConsoleLabGrant
}
return s.requireLabSafety(ctx, resolution, acknowledge)
}

func (s *ConsoleService) prepareLabGrant(ctx context.Context, actor domain.ActorContext, req ConsoleLabGrantIssueRequest, beneficiary domain.ActorID, resolution TargetResolution, identity, id string, existing ConsoleLabGrant, exists bool) (ConsoleLabGrant, error) {
now := s.recovery.now()
grant := ConsoleLabGrant{Mode: req.Mode, AcknowledgeExternalEffects: req.AcknowledgeExternalEffects, SchemaVersion: 1, GrantID: id, Target: domain.MachineRef(resolution.Locator.String()), EnrollmentIdentity: identity,
Issuer: actor.EffectiveActor, Beneficiary: beneficiary, Reason: req.Reason, IdempotencyKey: req.IdempotencyKey,
IssuedAt: now, ExpiresAt: now.Add(time.Duration(req.ValidForMillis) * time.Millisecond)}
if req.Mode == ConsoleLabModePersistentVM {
grant.ExpiresAt = time.Time{}
}
if exists {
grant.IssuedAt, grant.ExpiresAt = existing.IssuedAt, existing.ExpiresAt
if grant != existing || (req.Mode == "" && existing.ExpiresAt.Sub(existing.IssuedAt).Milliseconds() != req.ValidForMillis) {
return ConsoleLabGrant{}, receipt.ErrIdempotencyCollision
}
if err := s.validateLabBinding(ctx, existing); err != nil {
return ConsoleLabGrant{}, err
}
}

return grant, nil
}
41 changes: 30 additions & 11 deletions internal/app/console_lab_active.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,15 @@ import (

// ActiveLabGrant discovers only the caller's currently usable authority for the enrolled VM.
func (s *ConsoleService) ActiveLabGrant(ctx context.Context, actor domain.ActorContext, reference string) (ConsoleLabGrantStatus, error) {
return s.activeLabGrant(ctx, actor, reference, false)
}

func (s *ConsoleService) activeLabGrant(ctx context.Context, actor domain.ActorContext, reference string, persistentOnly bool) (ConsoleLabGrantStatus, error) {
disabled := ConsoleLabGrantStatus{State: "disabled"}
if actor.Validate() != nil || actor.IsDelegated() {
return disabled, ErrInvalidConsoleLabGrant
}
if err := s.validateDependencies(); err != nil {
if err := s.recovery.validateDependencies(); err != nil {
return disabled, err
}
resolution, err := s.target.ResolveTarget(ctx, reference)
Expand All @@ -43,14 +47,7 @@ func (s *ConsoleService) ActiveLabGrant(ctx context.Context, actor domain.ActorC
return disabled, err
}
defer file.Close()
entries, err := file.ReadDir(129)
if err != nil && !errors.Is(err, io.EOF) {
return disabled, err
}
if len(entries) > 128 {
return disabled, ErrInvalidConsoleLabGrant
}
selected, err := s.selectActiveLabGrant(ctx, actor, domain.MachineRef(resolution.Locator.String()), entries)
selected, err := s.scanActiveLabGrants(ctx, file, actor, domain.MachineRef(resolution.Locator.String()), persistentOnly)
if err != nil {
return disabled, err
}
Expand All @@ -60,7 +57,7 @@ func (s *ConsoleService) ActiveLabGrant(ctx context.Context, actor domain.ActorC
return ConsoleLabGrantStatus{Grant: selected, State: "active"}, nil
}

func (s *ConsoleService) selectActiveLabGrant(ctx context.Context, actor domain.ActorContext, canonical domain.MachineRef, entries []os.DirEntry) (ConsoleLabGrant, error) {
func (s *ConsoleService) selectActiveLabGrant(ctx context.Context, actor domain.ActorContext, canonical domain.MachineRef, entries []os.DirEntry, persistentOnly bool) (ConsoleLabGrant, error) {
var selected ConsoleLabGrant
for _, entry := range entries {
if err := ctx.Err(); err != nil {
Expand All @@ -71,7 +68,7 @@ func (s *ConsoleService) selectActiveLabGrant(ctx context.Context, actor domain.
continue
}
grant, err := s.loadLabGrant(ctx, id)
if err != nil || grant.Beneficiary != actor.EffectiveActor || grant.Target != canonical || s.requireActiveLabGrant(ctx, grant) != nil {
if err != nil || (persistentOnly && grant.Mode != ConsoleLabModePersistentVM) || grant.Beneficiary != actor.EffectiveActor || grant.Target != canonical || s.requireActiveLabGrant(ctx, grant) != nil {
continue
}
if selected.GrantID == "" || grant.IssuedAt.After(selected.IssuedAt) || (grant.IssuedAt.Equal(selected.IssuedAt) && grant.GrantID > selected.GrantID) {
Expand All @@ -80,3 +77,25 @@ func (s *ConsoleService) selectActiveLabGrant(ctx context.Context, actor domain.
}
return selected, nil
}

func (s *ConsoleService) scanActiveLabGrants(ctx context.Context, file *os.File, actor domain.ActorContext, canonical domain.MachineRef, persistentOnly bool) (ConsoleLabGrant, error) {
var selected ConsoleLabGrant
for {
entries, readErr := file.ReadDir(128)
if readErr != nil && !errors.Is(readErr, io.EOF) {
return ConsoleLabGrant{}, readErr
}
candidate, err := s.selectActiveLabGrant(ctx, actor, canonical, entries, persistentOnly)
if err != nil {
return ConsoleLabGrant{}, err
}
if candidate.GrantID != "" && (selected.GrantID == "" || candidate.IssuedAt.After(selected.IssuedAt) || (candidate.IssuedAt.Equal(selected.IssuedAt) && candidate.GrantID > selected.GrantID)) {
selected = candidate
}
if errors.Is(readErr, io.EOF) {
break
}
}

return selected, nil
}
6 changes: 3 additions & 3 deletions internal/app/console_lab_active_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ func TestConsoleLabActiveDiscoverySelectsOwnNewestAuthority(t *testing.T) {
}
}

func TestConsoleLabActiveDiscoveryRejectsStaleAndOversizedDirectory(t *testing.T) {
func TestConsoleLabActiveDiscoveryRejectsStaleAndStreamsHistoricalDirectory(t *testing.T) {
f := newConsoleFixture(t)
_, epoch := configureLab(f)
issueLab(t, f)
Expand All @@ -62,7 +62,7 @@ func TestConsoleLabActiveDiscoveryRejectsStaleAndOversizedDirectory(t *testing.T
t.Fatal(err)
}
}
if _, err := f.service.ActiveLabGrant(context.Background(), labActor(t), "default"); err == nil {
t.Fatal("unbounded directory discovery accepted")
if _, err := f.service.ActiveLabGrant(context.Background(), labActor(t), "default"); err != nil {
t.Fatalf("historical directory blocked discovery: %v", err)
}
}
Loading
Loading