guest: enforce app compose version policy

Author: kvinwang

dstack-types/src/lib.rs

@@ -67,7 +67,8 @@ impl TdxAttestationVariant {
 
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct AppCompose {
-    pub manifest_version: u32,
+    #[serde(deserialize_with = "deserialize_manifest_version")]
+    pub manifest_version: String,
     pub name: String,
     // Deprecated
     #[serde(default)]
@@ -105,6 +106,97 @@ pub struct AppCompose {
     /// optional port whitelist).
     #[serde(default)]
     pub port_policy: PortPolicy,
+    /// OS-version constraints enforced by guests that understand this field.
+    /// Use manifest_version "3" (string) when setting this field so older
+    /// guests, which only accept numeric manifest versions, fail closed instead
+    /// of silently ignoring the policy.
+    #[serde(default, skip_serializing_if = "OsVersionPolicy::is_empty")]
+    pub os_version_policy: OsVersionPolicy,
+}
+
+/// Manifest-level OS version constraints.
+///
+/// Only `min` is supported by the current schema. Unknown fields are rejected so
+/// authors cannot accidentally rely on a policy that this guest does not
+/// enforce.
+#[derive(Deserialize, Serialize, Debug, Clone, Default, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct OsVersionPolicy {
+    /// Minimum dstack OS version required by this app, e.g. "0.6.1".
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub min: Option<String>,
+}
+
+impl OsVersionPolicy {
+    pub fn is_empty(&self) -> bool {
+        self.min.is_none()
+    }
+}
+
+fn deserialize_manifest_version<'de, D>(deserializer: D) -> Result<String, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    struct ManifestVersionVisitor;
+
+    impl<'de> serde::de::Visitor<'de> for ManifestVersionVisitor {
+        type Value = String;
+
+        fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            formatter.write_str("a string manifest version, or legacy numeric 1/2")
+        }
+
+        fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+        where
+            E: serde::de::Error,
+        {
+            parse_manifest_version_string(value).map_err(E::custom)
+        }
+
+        fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
+        where
+            E: serde::de::Error,
+        {
+            self.visit_str(&value)
+        }
+
+        fn visit_u64<E>(self, value: u64) -> Result<Self::Value, E>
+        where
+            E: serde::de::Error,
+        {
+            match value {
+                1 | 2 => Ok(value.to_string()),
+                _ => Err(E::custom(
+                    "numeric manifest_version is only supported for legacy versions 1 and 2; use a string for newer versions",
+                )),
+            }
+        }
+
+        fn visit_i64<E>(self, value: i64) -> Result<Self::Value, E>
+        where
+            E: serde::de::Error,
+        {
+            let value = u64::try_from(value)
+                .map_err(|_| E::custom("manifest_version must be a positive integer"))?;
+            self.visit_u64(value)
+        }
+    }
+
+    deserializer.deserialize_any(ManifestVersionVisitor)
+}
+
+fn parse_manifest_version_string(value: &str) -> Result<String, String> {
+    let value = value.trim();
+    if value.is_empty() {
+        return Err("manifest_version must not be empty".to_string());
+    }
+    let parsed = value.parse::<u32>().map_err(|_| {
+        format!("manifest_version must be a positive integer string, got {value:?}")
+    })?;
+    if parsed == 0 {
+        return Err("manifest_version must be greater than 0".to_string());
+    }
+    Ok(parsed.to_string())
 }
 
 #[derive(Deserialize, Serialize, Debug, Clone, Default)]
@@ -180,6 +272,10 @@ pub struct DockerConfig {
 }
 
 impl AppCompose {
+    pub fn manifest_version_u32(&self) -> Option<u32> {
+        self.manifest_version.parse().ok()
+    }
+
     pub fn feature_enabled(&self, feature: &str) -> bool {
         self.features.contains(&feature.to_string())
     }
@@ -208,6 +304,73 @@ impl AppCompose {
     }
 }
 
+#[cfg(test)]
+mod app_compose_tests {
+    use super::*;
+
+    fn parse_compose(manifest_version: serde_json::Value) -> serde_json::Result<AppCompose> {
+        serde_json::from_value(serde_json::json!({
+            "manifest_version": manifest_version,
+            "name": "test",
+            "runner": "docker-compose"
+        }))
+    }
+
+    #[test]
+    fn manifest_version_accepts_string_versions() {
+        let compose = parse_compose(serde_json::json!("3")).unwrap();
+        assert_eq!(compose.manifest_version, "3");
+        assert_eq!(compose.manifest_version_u32(), Some(3));
+    }
+
+    #[test]
+    fn manifest_version_accepts_legacy_numeric_1_and_2() {
+        assert_eq!(
+            parse_compose(serde_json::json!(1))
+                .unwrap()
+                .manifest_version,
+            "1"
+        );
+        assert_eq!(
+            parse_compose(serde_json::json!(2))
+                .unwrap()
+                .manifest_version,
+            "2"
+        );
+    }
+
+    #[test]
+    fn manifest_version_rejects_new_numeric_versions() {
+        let err = parse_compose(serde_json::json!(3)).unwrap_err();
+        assert!(err.to_string().contains("legacy versions 1 and 2"));
+    }
+
+    #[test]
+    fn os_version_policy_only_supports_min() {
+        let compose: AppCompose = serde_json::from_value(serde_json::json!({
+            "manifest_version": "3",
+            "name": "test",
+            "runner": "docker-compose",
+            "os_version_policy": {
+                "min": "0.6.1"
+            }
+        }))
+        .unwrap();
+        assert_eq!(compose.os_version_policy.min.as_deref(), Some("0.6.1"));
+
+        let err = serde_json::from_value::<AppCompose>(serde_json::json!({
+            "manifest_version": "3",
+            "name": "test",
+            "runner": "docker-compose",
+            "os_version_policy": {
+                "deny": ["0.6.2"]
+            }
+        }))
+        .unwrap_err();
+        assert!(err.to_string().contains("unknown field"));
+    }
+}
+
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct SysConfig {
     #[serde(default)]

dstack-util/src/system_setup.rs

@@ -20,6 +20,7 @@ use dstack_types::{
         APP_COMPOSE, APP_KEYS, DECRYPTED_ENV, DECRYPTED_ENV_JSON, ENCRYPTED_ENV,
         HOST_SHARED_DIR_NAME, HOST_SHARED_DISK_LABEL, INSTANCE_INFO, SYS_CONFIG, USER_CONFIG,
     },
+    version::Version,
     KeyProvider, KeyProviderInfo,
 };
 use fs_err as fs;
@@ -372,6 +373,8 @@ const GATEWAY_CACHE_PATH: &str = "/run/dstack/gateway-cache.json";
 const WG_CONFIG_PATH: &str = "/etc/wireguard/dstack-wg0.conf";
 /// Certificate validity period in seconds (10 days)
 const CERT_VALIDITY_SECS: u64 = 10 * 24 * 3600;
+const MAX_SUPPORTED_MANIFEST_VERSION: u32 = 3;
+const OS_VERSION_POLICY_MANIFEST_VERSION: u32 = 3;
 
 #[derive(Serialize, Deserialize, Clone)]
 struct GatewayKeyStore {
@@ -759,6 +762,106 @@ fn emit_key_provider_info(provider_info: &KeyProviderInfo) -> Result<()> {
     Ok(())
 }
 
+fn verify_manifest_version(app_compose: &AppCompose) -> Result<u32> {
+    let manifest_version = app_compose
+        .manifest_version_u32()
+        .context("Invalid manifest_version")?;
+    if manifest_version > MAX_SUPPORTED_MANIFEST_VERSION {
+        bail!(
+            "Unsupported manifest_version: {manifest_version}, max supported: {MAX_SUPPORTED_MANIFEST_VERSION}"
+        );
+    }
+    Ok(manifest_version)
+}
+
+fn verify_app_compose_policy(app_compose: &AppCompose) -> Result<()> {
+    let manifest_version = verify_manifest_version(app_compose)?;
+    if app_compose.os_version_policy.min.is_some() {
+        let current_os_version =
+            read_current_os_version().context("Failed to read current dstack OS version")?;
+        verify_os_version_policy(app_compose, manifest_version, &current_os_version)?;
+    }
+    Ok(())
+}
+
+fn verify_os_version_policy(
+    app_compose: &AppCompose,
+    manifest_version: u32,
+    current_os_version: &str,
+) -> Result<()> {
+    let Some(min_os_version) = app_compose.os_version_policy.min.as_deref() else {
+        return Ok(());
+    };
+    if manifest_version < OS_VERSION_POLICY_MANIFEST_VERSION {
+        bail!(
+            "os_version_policy requires manifest_version >= {OS_VERSION_POLICY_MANIFEST_VERSION}; \
+             use string manifest_version \"{OS_VERSION_POLICY_MANIFEST_VERSION}\" so older guests fail closed"
+        );
+    }
+
+    let min_os_version = Version::parse(min_os_version)
+        .with_context(|| format!("Invalid os_version_policy.min: {min_os_version}"))?;
+    let current_os_version = Version::parse(current_os_version)
+        .with_context(|| format!("Invalid current dstack OS version: {current_os_version}"))?;
+    if current_os_version < min_os_version {
+        bail!(
+            "Unsupported dstack OS version: current {current_os_version}, required >= {min_os_version}"
+        );
+    }
+    info!(
+        "dstack OS version policy satisfied: current={}, min={}",
+        current_os_version, min_os_version
+    );
+    Ok(())
+}
+
+fn read_current_os_version() -> Result<String> {
+    const OS_RELEASE_PATHS: &[&str] = &["/etc/os-release", "/usr/lib/os-release"];
+    for path in OS_RELEASE_PATHS {
+        let content = match fs::read_to_string(path) {
+            Ok(content) => content,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(err) => return Err(err).with_context(|| format!("Failed to read {path}")),
+        };
+        if let Some(version) = os_release_value(&content, "VERSION_ID") {
+            return Ok(version);
+        }
+    }
+    bail!("VERSION_ID not found in /etc/os-release or /usr/lib/os-release")
+}
+
+fn os_release_value(content: &str, key: &str) -> Option<String> {
+    for line in content.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let Some((k, v)) = line.split_once('=') else {
+            continue;
+        };
+        if k == key {
+            return Some(unquote_os_release_value(v));
+        }
+    }
+    None
+}
+
+fn unquote_os_release_value(value: &str) -> String {
+    let value = value.trim();
+    let bytes = value.as_bytes();
+    if bytes.len() >= 2
+        && ((bytes[0] == b'"' && bytes[bytes.len() - 1] == b'"')
+            || (bytes[0] == b'\'' && bytes[bytes.len() - 1] == b'\''))
+    {
+        let inner = &value[1..value.len() - 1];
+        return inner
+            .replace("\\\"", "\"")
+            .replace("\\'", "'")
+            .replace("\\\\", "\\");
+    }
+    value.to_string()
+}
+
 pub async fn cmd_sys_setup(args: SetupArgs) -> Result<()> {
     let stage0 = Stage0::load(&args)?;
     let vmm = stage0.host_api();
@@ -770,6 +873,8 @@ pub async fn cmd_sys_setup(args: SetupArgs) -> Result<()> {
 }
 
 async fn do_sys_setup(stage0: Stage0<'_>) -> Result<()> {
+    verify_app_compose_policy(&stage0.shared.app_compose)
+        .context("Failed to verify app-compose policy")?;
     if stage0.shared.app_compose.secure_time {
         info!("Waiting for the system time to be synchronized");
         cmd! {
@@ -1902,3 +2007,56 @@ fn test_validate_luks2_header() {
         .to_string()
         .contains("Invalid LUKS keyslot encryption"));
 }
+
+#[cfg(test)]
+fn test_app_compose(
+    manifest_version: serde_json::Value,
+    min_os_version: Option<&str>,
+) -> AppCompose {
+    let mut value = serde_json::json!({
+        "manifest_version": manifest_version,
+        "name": "test",
+        "runner": "docker-compose"
+    });
+    if let Some(min_os_version) = min_os_version {
+        value["os_version_policy"] = serde_json::json!({
+            "min": min_os_version
+        });
+    }
+    serde_json::from_value(value).unwrap()
+}
+
+#[test]
+fn test_manifest_version_policy_rejects_above_guest_max() {
+    let app_compose = test_app_compose(serde_json::json!("4"), None);
+    let err = verify_manifest_version(&app_compose).unwrap_err();
+    assert!(err.to_string().contains("Unsupported manifest_version"));
+}
+
+#[test]
+fn test_os_version_policy_requires_v3_manifest() {
+    let app_compose = test_app_compose(serde_json::json!("2"), Some("0.6.1"));
+    let err = verify_os_version_policy(&app_compose, 2, "0.6.1").unwrap_err();
+    assert!(err.to_string().contains("requires manifest_version"));
+}
+
+#[test]
+fn test_os_version_policy_rejects_too_old_os() {
+    let app_compose = test_app_compose(serde_json::json!("3"), Some("0.6.1"));
+    let err = verify_os_version_policy(&app_compose, 3, "0.6.0").unwrap_err();
+    assert!(err.to_string().contains("Unsupported dstack OS version"));
+    verify_os_version_policy(&app_compose, 3, "0.6.1").unwrap();
+    verify_os_version_policy(&app_compose, 3, "0.6.2").unwrap();
+}
+
+#[test]
+fn test_os_release_value_parses_quoted_version_id() {
+    let content = r#"
+NAME="DStack"
+VERSION_ID="0.6.1"
+"#;
+    assert_eq!(
+        os_release_value(content, "VERSION_ID").as_deref(),
+        Some("0.6.1")
+    );
+}

guest-agent/src/rpc_service.rs

@@ -700,7 +700,7 @@ mod tests {
         temp_attestation_file.flush().unwrap();
 
         let dummy_appcompose = AppCompose {
-            manifest_version: 0,
+            manifest_version: "2".to_string(),
             name: String::new(),
             features: Vec::new(),
             runner: String::new(),
@@ -719,6 +719,7 @@ mod tests {
             storage_fs: None,
             swap_size: 0,
             port_policy: Default::default(),
+            os_version_policy: Default::default(),
         };
 
         let dummy_appcompose_wrapper = AppComposeWrapper {