风格指南¶

以下规则旨在确保 MASTG 的一致性

保持内容真实、简短和重点突出。避免重复指南的其他部分；
避免宣传商业工具或服务；
在提供技术指导时，以第二人称称呼读者。

技术写作

我们建议您在为 MAS 项目编写或审查内容时参加这些免费的 Google 课程

1. 如何撰写内容¶

基本原则¶

确保内容具有凝聚力和连贯性

清晰且合乎逻辑地连接想法。
确保每个段落本身都有意义，并且与前后的段落相符。
删除不必要的单词。使用清晰、简洁的语言，而不是冗长或啰嗦的句子。
构建内容以便于扫描。尽可能使用项目符号而不是密集的段落。
尽可能将被动语态转换为主动语态。
保持每个段落专注于一个主题或想法。
以要点开始每个部分，以指导读者。
正确使用标点符号，包括逗号、括号、冒号、破折号和分号。

内容量¶

页面内容量的主要衡量标准应基于其服务的目的。

使用短页面¶

最多包含一两个屏幕的文本。用户正在扫描链接选项。在章节中更深层地使用较长的页面（需要更多滚动或阅读的页面），以便可以打印和稍后阅读内容。

对于非常大的信息部分¶

考虑创建支持文档并从页面链接到它，而不是直接在页面上显示所有信息。

性别中立¶

MASTG 面向全球各种各样的人。为了确保包容性和多样性，请避免在整本书中使用以下内容

她/她的/她的/她自己
他/他的/他/他自己

或任何其他结构，如“他/她”、“s/he”、“他或她”。而是使用以下性别中立的替代方案

如果可能，省略代词：“用户使用...验证他自己” -> “用户使用...验证”
用“the”或“a”替换代词：“当用户输入他的密码...” -> “当用户输入密码...”
使用复数名词和代词：“攻击者将使用他的越狱设备...” -> “攻击者将使用他们的越狱设备...”
使用第二人称：“如果攻击者运行此代码，他可以绕过...” -> “如果你运行此代码，你可以绕过...”
使用祈使句：“开发人员永远不应该在他的代码中使用...” -> “永远不要在你的代码中使用...”！

内容的及时性¶

保持准确和及时的内容使 OWASP MAS 可交付成果成为可信赖的信息来源。

在页面上使用统计数据时，请确保信息是最新的，并附有数据的来源以及数据的编译日期。

数字平台与印刷的内容¶

编写简洁的内容，用户可以快速有效地阅读。对于数字内容 - 创建相互链接的较短页面。如果您的内容可能会被打印，请创建一个较长的页面。

受众¶

为具有基本技术理解的国际受众写作，即他们有手机并且知道如何安装应用程序。避免难以翻译的俚语/短语，以确保非英语母语的读者可以访问内容。

语境和定位¶

让用户知道他们在每个页面上的位置。通过使用唯一的页面标题来确立主题。

尽可能包括清晰简洁的介绍。

在必要时链接到背景信息。

写作让人们愉快阅读¶

使用以下方法来提高可扫描性

标题、副标题和文本使用左对齐
在适当的地方链接
尽可能使用列表而不是段落
列表使用破折号-而不是星号*
每个段落只包含一个主要思想
将最重要的信息放在顶部
以结论和剩余内容的简短摘要开始页面
在适用的地方使用标题
使用简短、简单的单词，切中要点
简洁且重点突出

对于较长的页面，使用以下工具使页面易于扫描

锚链接
副标题和相关链接
项目符号副本
有意义的图形或摘录，以打破较大的文本块
结尾链接

有效使用列表¶

以列表格式呈现内容时

当条目的顺序很重要时，使用编号列表。
只要条目的顺序不重要，就使用项目符号列表。
通常，将单个列表中的项目数量限制为不超过九个。
通常，将列表限制为不超过两个级别：主要和次要。
一致地标点和大小写列表项（CMOS 6.124-6.126）。
不要向非完整句子的列表项添加结尾标点符号，除非它们完成介绍列表的句子。
对单独构成完整句子的列表项使用适当的大写和结尾标点符号。
如果列表项完成介绍性句子，则用逗号结束每个列表项（最后一个除外），并且不要在倒数第二个项目后添加“and”。用适当的结尾标点符号结束最后一项（通常是句点）。

编号约定¶

当使用零到十之间的数字时，拼写出数字（例如，“three”或“ten”）。

当使用任何大于十的数字时，使用数字版本（例如，“12”或“300”）。

2. 语言¶

美式拼写和术语¶

使用美式拼写和术语。

在适用的情况下，将所有英式拼写和术语更改为美式等效词。这包括“toward”（美国）与“towards”（英国），“among”（美国）与“amongst”（英国），“analyze”（美国）与“analyse”（英国），“behavior”（美国）与“behaviour”（英国）等。

复数¶

在典型的单词的复数形式方面，坚持标准语法和标点符号规则。

日历年份的复数形式在“s”之前不带撇号。例如，1990 的复数形式是 1990s。

标题大写¶

我们遵循“芝加哥格式手册”中的标题大小写规则

无论词性如何，标题中的第一个和最后一个单词都要大写
将所有名词（app、encryption、package）、代词（you、she、it）、动词（analyze、compile、inspect）、形容词（active、insecure、weak）、副词（immediately、quietly）和从属连词（as、because、although）大写
将不定式中的“to”小写
将所有冠词（a、the）、介词（to、at、in、with）和并列连词（and、but、or）小写

如有疑问，您可以在https://titlecaseconverter.com/上验证正确的大小写。

标准化¶

MAS 项目（MASVS、MASTG、MASWE）力求使用在语境中清晰且明确的措辞。但是，由于项目规模很大，可能存在使用不一致且需要标准化的单词或缩写。如果是这种情况，请提交拉取请求，以便我们可以讨论它们并建议应使用哪些内容。

缩略形式¶

使用以下常用缩略形式

are not -> aren't
cannot -> can't
could not -> couldn't
did not -> didn't
do not -> don't
does not -> doesn't
has not -> hasn't
had not -> hadn't
have not -> haven't
is not -> isn't
it is -> it's
that is -> that's
there is -> there's
was not -> wasn't
were not -> weren't
will not -> won't
would not -> wouldn't
you are -> you're
you have + verb -> you've + verb
you will -> you'll

缩写¶

缩写包括首字母缩略词、首字母缩写词、缩短的单词和缩略形式。

第一次使用时拼出该术语，然后在括号中加上缩写。示例：OWASP 移动应用程序安全测试指南 (MASTG)。在同一章节中后续使用时，可能只包括缩写。
如果它只在内容中出现一次，请拼出该术语，而不是使用缩写。
在标题中，使用缩写，但请务必在后面的文本中正确介绍它（参见上文）。
根据首字母缩略词的发音使用“a”或“an”。示例：a DLL、an APK、a URL、a SQL。
添加一个“s”作为复数形式，除非缩写已经代表一个复数名词。示例：the APIs、CSS（不是 CSSs）。
如果缩写比其完整的拼写术语更广为人知，请仅使用缩写。示例：PDF、URL、USB、ZIP。

以下代码段演示了这些要点中的大多数

## JAR Files

JAR (Java ARchive) files are [...]

APKs are packed using the ZIP format. An APK is a variation of a JAR file [...]

对于常用的文件格式（如 APK、IPA 或 ZIP），除非您明确引用文件扩展名，否则请不要将它们称为“.apk”、“ipa”或“.zip”。

引用 Android 版本¶

引用 Android 版本时，使用以下格式：Android X（API 级别 YY）。不鼓励使用描述性名称（例如：Oreo）。

示例：Android 9（API 级别 28）

在测试用例中称呼读者¶

在本指南中，您可能希望称呼读者，以便告诉他们该做什么或他们应该注意什么。对于任何此类情况，使用主动方法，只需使用“you”来称呼读者。

正确：如果打开 AndroidManifest.xml 文件，您将看到一个主要 Application 标签，具有以下属性：atr1、atr2 和 atr3。如果您运行以下命令，您将看到 atr1 实际上是危险的：[...]。

错误：AndroidManifest.xml 文件包含一个 Application 标签，具有以下属性：atr1、atr2 和 atr3。以下命令显示 atr1 是危险的：[...]。

错误：如果打开 AndroidManifest.xml 文件，我们将看到一个主要 Application 标签，具有以下属性：atr1、atr2 和 atr3。如果我们运行以下命令，我们将看到 atr1 实际上是危险的：[...]。

3. 外部引用¶

网络链接¶

使用 markdown 的内联链接格式 (A) [TEXT](URL "TITLE") 或 (B) [TEXT](URL)。

例如

The [threat modeling guidelines defined by OWASP](https://owasp.org/www-community/Threat_Modeling "OWASP Threat Modeling") are generally applicable to mobile apps.

当使用 (A) 时，请务必转义特殊字符，例如撇号 (\') 或单引号 (`)，否则链接将在 Gitbook 中断开。

错误用法，请参见“iPhone's”

[UDID of your iOS device via iTunes](https://medium.com/@igor_marques/how-to-find-an-iphones-udid-2d157f1cf2b9 "How to Find Your iPhone's UDID")

正确用法，请参见“iPhone\'s”

[UDID of your iOS device via iTunes](https://medium.com/@igor_marques/how-to-find-an-iphones-udid-2d157f1cf2b9 "How to Find Your iPhone\'s UDID")

在章节末尾的“引用”部分中添加链接时，请使用- Title - <url>。这是强制 latex 正确打印 PDF 的 URL 所必需的。

例如

- adb - <https://developer.android.com.cn/studio/command-line/adb>

书籍和论文¶

对于书籍和论文，请使用以下格式：[#NAME]。

并在 markdown 文件末尾的“引用”部分手动包含完整引用。示例

An obfuscated encryption algorithm can generate its key (or part of the key)
using data collected from the environment [#riordan].

并在章节末尾的“引用”部分

- [#riordan] -  James Riordan, Bruce Schneier. Environmental Key Generation towards Clueless Agents. Mobile Agents and Security, Springer Verlag, 1998

论文

引用技术报告的一般形式是将公司或机构的名称和位置放在作者和标题之后，并在引用的末尾给出报告编号和日期。

基本格式

- [shortname] J. K. Author, "Title of report," Abbrev. Name of Co., City of Co., Abbrev. State, Rep. xxx, year

- [shortname] \[Author(s)\], \[Title\] - Link

书籍

- [shortname] \[Author(s)\], \[Title\], \[Published\], \[Year\]

- [examplebook] J. K. Author, "Title of chapter in the book," in Title of His Published Book, xth ed. City of Publisher, Country if not USA: Abbrev. of Publisher, year, ch. x, sec. x, pp. xxx-xxx.

注意：给出三个或更多名称时，请使用 et al。

例如

- [klaus] B. Klaus and P. Horn, Robot Vision. Cambridge, MA: MIT Press, 1986.
- [stein] L. Stein, "Random patterns," in Computers and You, J. S. Brake, Ed. New York: Wiley, 1994, pp. 55-70.
- [myer] R. L. Myer, "Parametric oscillators and nonlinear materials," in Nonlinear Optics, vol. 4, P. G. Harper and B. S. Wherret, Eds. San Francisco, CA: Academic, 1977, pp. 47-160.
- [abramowitz] M. Abramowitz and I. A. Stegun, Eds., Handbook of Mathematical Functions (Applied Mathematics Series 55). Washington, DC: NBS, 1964, pp. 32-33.

4. 指南内部引用¶

对于 MASTG 中其他章节的引用，只需命名章节，例如：另请参见“基本安全测试”章节、参见“基本安全测试”章节中的“Apktool”部分等。MASTG 应该便于作为印刷书籍阅读，因此请谨慎使用内部引用。或者，您可以为特定部分创建链接

See the section "[App Bundles](0x05a-Platform-Overview.md#app-bundles)" in the chapter ...

请注意，在这种情况下，锚点（#之后的所有内容）应为小写，空格应替换为连字符。

5. 插入图片¶

图片必须始终是 HTML <img 元素，而不是通常的 markdown 图片格式。

src 是第一个值。
可以指定width。
它们必须包含在相应的目录中，例如，MASTG 章节的 Document/Images/Chapters 中。

例如

<img src="Images/Chapters/0x05b/r2_pd_10.png" width="80%" />

6. 标点符号约定¶

冒号后使用小写或大写字母¶

芝加哥格式手册（6.61：冒号后使用小写或大写字母）说：除非它是专有名词或至少两个完整句子的开头或直接问题，否则小写第一个单词。

系列逗号的使用¶

对于三个或更多项目的列表中的最后一个项目，在“and”之前使用系列逗号。例如

我们从商店买了苹果、橙子和西红柿。

引号和撇号¶

使用直双引号、直单引号和直撇号（不是弯引号/撇号）。

技术术语¶

按照公司使用的拼写/标点符号特定技术术语（例如，使用公司网站）。

按照优先顺序拼写/标点符号通用技术术语

Merriam Webster's Collegiate Dictionary，第 11 版。
Microsoft Manual of Style，第 4 版
foldoc.org（计算机免费在线词典）

名词形式	形容词形式
App Store	NA
后端	后端
Base64	Base64-
黑盒	相同
Bundle ID	NA
字节码	NA
客户端	客户端
代码库	相同
代码签名	相同
命令行	相同
反汇编器	NA
最终用户	NA
文件名	相同
macOS	NA
OS X	NA
渗透测试	相同
PhoneGap	NA
Python	NA
重新打包	NA
运行时	相同
服务器端	服务器端
快照长度	NA
用例	相同
Wi-Fi	相同
白盒	相同

7. 注释¶

Markdown 块引用可以通过使用 > 用于文档中的注释

> This is a blockquote

8. 代码和 Shell 命令¶

包括示例代码、shell 命令和路径时，请使用代码块。在 Markdown 中，代码块由三个反引号 (```) 表示。 GitHub 还支持各种语言的语法突出显示。例如，Java 代码块应按如下方式注释

```java
public static void main(String[] args) { System.out.println(" Hello World!"); } } ;
```

这将产生以下结果

public static void main(String[] args) { System.out.println(" Hello World!"); } }

包括 shell 命令时，请确保使用正确的语言进行语法突出显示（例如 shell 或 bash），并从命令中删除任何提示（主机名、用户名、...），例如

```shell
echo 'Hello World'
Hello World
```

当命令需要读者修改的参数时，用尖括号将它们括起来

adb pull <remote_file> <target_destination>

文本中的关键字¶

当它们没有出现在代码块中时，请根据表将以下与代码相关的关键字放在反引号 (``)、双直引号 ("") 中或不加标点符号

反引号	引号	无标点符号
函数名	节标题	应用程序名称
方法名	章节标题	文件夹名称
命令	书名	内存地址（例如 0x100044520）
类名	标志值（例如，“true”，小写）
块名称	命令选项（例如，“help”选项）
标志名称	单个菜单项（例如，“Home”菜单）
文件名	系统错误消息
包名
文件路径
密码
端口号
二进制文件名
方法/函数参数
方法/函数参数或返回值（例如，`true`、`0`、`YES`）
XML 属性（例如，iOS Plists 上的 `get-task-allow`，Android Manifests 上的 `"@string/app_name"`）
XML 属性值（例如，Android Manifests 上的 `android:label`）
属性名称
对象名称
API 调用
接口名称

如果反引号中的名词是复数，请在第二个反引号后放置“s”（例如 RuntimeExceptions）。不要向反引号中的任何关键字添加括号、方括号或其他标点符号（例如，main，而不是 main()）。

通过名称引用任何 UI 元素时，使用 **<name>** 将其名称加粗（例如，Home -> Menu）。