proposal: syscall: update Windows SysProcAttr for recent process creation features

[rsc]

Proposal Details

I propose to update syscall.SysProcAttr on Windows to let callers control the following process creation parameters:

• The job object list for the new process.
• The console for the new process.
• The desktop for the new process.
• The AppContainer configuration for the new process.
• (Added, July 28) The experimental sandbox configuration for the new process.

In general package syscall is frozen. However, one exception is details that affect process creation through os/exec, because otherwise the only way to make such calls is to fork both syscall and os/exec.

The API change is these new fields in syscall.SysProcAttr on Windows:

	Jobs                       []Handle            // if non-nil, start the process with this job object list
	Console                    Handle              // if non-zero, start the process connected to this console
	Desktop                    string              // if non-empty, start the process on the named desktop
	AppContainer               *AppContainer       // if set, create AppContainer process with this metadata
	Sandbox                    *Sandbox            // if non-nil, start the process in the described sandbox

And a new type, AppContainer:

// An AppContainer defines parameters for creating a process in an AppContainer.
// It is a safe Go version of the Windows SECURITY_CAPABILITIES structure.
// See https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-security_capabilities.
type AppContainer struct {
	SID          *SID
	Capabilities []SIDAndAttributes
 }

We could instead define SecurityCapabilities to be the literal Windows struct, but that Windows struct is unsafe and also may possibly change in the future. The #if in the documentation page definition look scary. It seemed cleaner to give it an appropriate name and use a Go slice. Then if the actual struct passed to the Windows call varies by OS version, that's an implementation detail and not an API detail.

And also a new type Sandbox (added July 28):

// A Sandbox defines parameters for creating a process in an experimental sandbox.
// See https://learn.microsoft.com/en-us/windows/win32/secauthz/createprocessinsandbox.
type Sandbox struct {
    Identity string  // sandbox name
    Spec     []byte  // FlatBuffer-encoded specification; see Microsoft docs
}

That is the entire API change. I have used the AppContainer part of this API successfully to implement basic sandboxing of Windows programs using AppContainer. I have not used the Sandbox part since Microsoft has not yet enabled the API on my Windows system (you can call it but it says not supported), but given the recent launch of https://github.com/microsoft/mxc, it seems likely they will enable it in the coming six months, so having it ready for the Feb 2027 Go release seems worthwhile.

There is no support in package syscall for constructing a sandbox spec. We could add that instead to golang.org/x/sys/windows, where it can be more easily updated. This proposal is concerned with the minimal amount necessary to enable use of the new functionality through os/exec.

The AppContainer details in this proposal are a safer version of the accepted proposal #65611. I suggest we do the API in this proposal instead of #65611, because in general we keep syscall.SysProcAttr type-safe, even on Windows.

The job object details in this proposal mostly match the undiscussed proposal #79927.

The desktop details in this proposal address the feature requested in #42836.

The implementation (except for Sandbox) is at CL 801640.

[gabyhelp]

Related Issues

• x/sys/windows: allow specifying Security Capabilities in SysProcAttr #65611
• proposal: os/exec: allow on windows to add a JOB_OBJECT on process creation #79927
• syscall: StartProcess should accept Desktop property for StartupInfo for Windows #42836

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/801640 mentions this issue: syscall: update Windows SysProcAttr with new features

[rsc]

One reason for these features is to create sandboxes of various kinds. Microsoft has recently (May 26) documented a new sandbox creation method Experimental_CreateProcessInSandbox, which https://github.com/microsoft/mxc uses. This feature appears to be disabled even on the latest Windows 11 builds, but the use in MXC suggests that it will be enabled relatively soon. I'd like to get ahead of this and make sure that Go can use this new API when it does become available.

That would mean adding another field to SysProcAttr:

Sandbox *Sandbox

where Sandbox is defined as:

type Sandbox struct {
    Identity string
    Spec []byte
}

Right now Windows has two different process creation mechanisms: CreateProcess and CreateProcessAsUser. The logic for deciding which is:

if sys.Token != 0 {
    CreateProcessAsUser(token, shared args...)
} else {
    CreateProcess(shared args...)
}

Adding the two new Experimental_CreateProcessInSandbox and Experimental_CreateProcessAsUserInSandbox expands this branch:

switch {
case sys.Sandbox != nil && sys.Token != 0:
    Experimental_CreateProcessAsUserInSandbox(token, shared args..., sys.Sandbox.Identity, sys.Sandbox.Spec)
case sys.Sandbox != nil:
    Experimental_CreateProcessInSandbox(shared args..., sys.Sandbox.Identity, sys.Sandbox.Spec)
case sys.Token != 0:
    CreateProcessAsUser(token, shared args...)
default:
    CreateProcess(shared args...)
}

It's a little annoying but it's not bad, and it's probably the best we can do given the API choices. Certainly far better than having to fork all of StartProcess just to use the new sandbox functionality. After posting this comment I will update my top message to include the new Sandbox field.

[magical]

Experimental_CreateProcessInSandbox seems to be, as the prefix suggests, well, experimental. The linked article has the following warning and you say that it is not even enabled in recent windows builds.

These APIs are experimental and subject to change.

Surely it's too early to lock in support for such a feature.

[rsc]

@magical This is a completely reasonable objection, and in general I'd agree. However, I think these mitigating factors weigh in favor of making the change here in package syscall:

• In the absolute worst case, if the API were deleted entirely, we'd be left with a single field in a single struct that wouldn't be useful anymore. This is package syscall, though, and it's full of things that aren't generally useful.

• I think it's extremely unlikely that the API will be deleted entirely. In general Microsoft doesn't do that - they are one of the best companies ever at backwards compatibility. And despite the documented warning, they are confident enough to have (1) shipped the API in Windows 11 (you can read the code in processmodel.dll, it's a full implementation), (2) shipped a project using that API at https://github.com/microsoft/mxc, and (3) announced that project at their developer conference. This API is a key part of their agent sandboxing strategy.

• I think it's very unlikely that the API will be modified at the function signature level. Again the backwards compatibility point. Also, the change relative to the existing CreateProcess and CreateProcessAsUser is quite minimal: two new arguments (name and definition of sandbox). I can't see any reason Microsoft would need to change that decision. And again they have shipped the API with this signature, and people can already build the mxc tools today and get a program linked against it. They're very unlikely to make a breaking change at that level.

• I do think it is likely that the sandbox definition details will change. The []byte is a FlatBuffers-encoded data structure that is likely to add more fields over time (in fact, the mxc repo contains a spec with more fields than the web page lists). I believe that FlatBuffers was chosen here specifically because it supports schema evolution. That's why I used a raw []byte as the package syscall API instead of, say, defining a struct for the current sandbox spec and putting package syscall in charge of marshaling it. The callers can be in charge of deciding which version of the schema to use. And we can keep up with those schema changes, as appropriate, in golang.org/x/sys/windows. This proposal is the minimal change in package syscall to enable that.

• Without adding the field, it's very difficult to use this API correctly in a Go program. There are tons of subtle details in os/exec, os, and syscall that have to be forked and modified to get down to this level and substitute a different process creation call. The very tiny change in this proposal avoids much larger changes in calling code.

The next Go release (that this can be added to) won't be until February 2027. If the situation changes before then for the worse, it is easy to roll back. On the other hand, it is riskier to wait and then decide things look good and push through a last-minute change.

Update: Over on microsoft/mxc#693, where I asked about the release timeline, the response was that this feature is already available on Windows Insider Preview builds and that it is expected to GA later this year. That lines up well with the February 2027 timeline for the next Go release.

[aclements]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— aclements for the proposal review group

[seankhliao]

cc @golang/windows